@hotmeshio/hotmesh 0.0.57 → 0.0.58

package/build/services/activities/cycle.js

@@ -10,6 +10,7 @@ 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;
@@ -18,18 +19,21 @@ 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);
+            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;
@@ -58,7 +62,18 @@ 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,10 +6,16 @@ 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>;

package/build/services/activities/hook.js

@@ -8,10 +8,14 @@ const pipe_1 = require("../pipe");
 const task_1 = require("../task");
 const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
+/**
+ * Supports `signal hook`, `time hook`, and `cycle hook` patterns
+ */
 class Hook 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('hook-process', {
             jid: this.context.metadata.jid,
@@ -24,9 +28,11 @@ class Hook extends activity_1.Activity {
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
             if (this.doesHook()) {
+                //sleep and wait to awaken upon a signal
                 await this.doHook(telemetry);
             }
             else {
+                //end the activity and transition to its children
                 await this.doPassThrough(telemetry);
             }
             return this.context.metadata.aid;
@@ -55,6 +61,9 @@ class Hook extends activity_1.Activity {
             this.logger.debug('hook-process-end', { jid: this.context.metadata.jid, gid: this.context.metadata.gid, aid: this.metadata.aid });
         }
     }
+    /**
+     * does this activity use a time-hook or web-hook
+     */
     doesHook() {
         if (this.config.sleep) {
             const duration = pipe_1.Pipe.resolve(this.config.sleep, this.context);
@@ -106,6 +115,7 @@ class Hook extends activity_1.Activity {
             return this.context.metadata.jid;
         }
     }
+    //********  SIGNAL RE-ENTRY POINT  ********//
     async processWebHookEvent(status = stream_1.StreamStatus.SUCCESS, code = 200) {
         this.logger.debug('hook-process-web-hook-event', {
             topic: this.config.hook.topic,
@@ -124,8 +134,8 @@ class Hook extends activity_1.Activity {
             await this.processEvent(status, code, 'hook');
             if (code === 200) {
                 await taskService.deleteWebHookSignal(this.config.hook.topic, data);
-            }
-        }
+            } //else => 202/keep alive
+        } //else => already resolved
     }
     async processTimeHookEvent(jobId) {
         this.logger.debug('hook-process-time-hook-event', {

package/build/services/activities/interrupt.js

@@ -10,6 +10,7 @@ class Interrupt 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('interrupt-process', { jid: this.context.metadata.jid, gid: this.context.metadata.gid, aid: this.metadata.aid });
         let telemetry;
@@ -49,11 +50,14 @@ class Interrupt extends activity_1.Activity {
         }
     }
     async interruptSelf(telemetry) {
+        // Apply final updates to THIS job's state
         if (this.config.job?.maps) {
             this.mapJobData();
             await this.setState();
         }
+        // Interrupt THIS job
         const messageId = await this.interrupt();
+        // Notarize completion and log
         telemetry.mapActivityAttributes();
         const multi = this.store.getMulti();
         await collator_1.CollatorService.notarizeEarlyCompletion(this, multi);
@@ -67,8 +71,10 @@ class Interrupt extends activity_1.Activity {
         return this.context.metadata.aid;
     }
     async interruptAnother(telemetry) {
+        // Interrupt ANOTHER job
         const messageId = await this.interrupt();
         const attrs = { 'app.activity.mid': messageId };
+        // Apply updates to THIS job's state
         telemetry.mapActivityAttributes();
         this.adjacencyList = await this.filterAdjacent();
         if (this.config.job?.maps || this.config.output?.maps) {
@@ -77,12 +83,14 @@ class Interrupt extends activity_1.Activity {
             const multi = this.store.getMulti();
             await this.setState(multi);
         }
+        // Notarize completion
         const multi = this.store.getMulti();
         await collator_1.CollatorService.notarizeEarlyCompletion(this, multi);
         await this.setStatus(this.adjacencyList.length - 1, multi);
         const multiResponse = await multi.exec();
         const jobStatus = this.resolveStatus(multiResponse);
         attrs['app.job.jss'] = jobStatus;
+        // Transition next generation and log
         const messageIds = await this.transition(this.adjacencyList, jobStatus);
         if (messageIds.length) {
             attrs['app.activity.mids'] = messageIds.join(',');

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

@@ -8,7 +8,13 @@ declare class Signal extends Activity {
     process(): Promise<string>;
     mapSignalData(): Record<string, any>;
     mapResolverData(): Record<string, any>;
+    /**
+     * The signal activity will hook one
+     */
     hookOne(): Promise<string>;
+    /**
+     * The signal activity will hook all paused jobs that share the same job key.
+     */
     hookAll(): Promise<string[]>;
 }
 export { Signal };

package/build/services/activities/signal.js

@@ -11,6 +11,7 @@ class Signal 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('signal-process', { jid: this.context.metadata.jid, gid: this.context.metadata.gid, aid: this.metadata.aid });
         let telemetry;
@@ -18,6 +19,7 @@ class Signal extends activity_1.Activity {
             await this.verifyEntry();
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
+            //save state and notarize early completion (signals only run leg1)
             const multi = this.store.getMulti();
             this.adjacencyList = await this.filterAdjacent();
             this.mapOutputData();
@@ -26,12 +28,14 @@ class Signal extends activity_1.Activity {
             await collator_1.CollatorService.notarizeEarlyCompletion(this, multi);
             await this.setStatus(this.adjacencyList.length - 1, multi);
             const multiResponse = await multi.exec();
+            //todo: this should execute BEFORE the status is decremented
             if (this.config.subtype === 'all') {
                 await this.hookAll();
             }
             else {
                 await this.hookOne();
             }
+            //transition to adjacent activities
             const jobStatus = this.resolveStatus(multiResponse);
             const attrs = { 'app.job.jss': jobStatus };
             const messageIds = await this.transition(this.adjacencyList, jobStatus);
@@ -78,6 +82,9 @@ class Signal extends activity_1.Activity {
             return mapper.mapRules();
         }
     }
+    /**
+     * The signal activity will hook one
+     */
     async hookOne() {
         const topic = pipe_1.Pipe.resolve(this.config.topic, this.context);
         const signalInputData = this.mapSignalData();
@@ -85,15 +92,23 @@ class Signal extends activity_1.Activity {
         const code = pipe_1.Pipe.resolve(this.config.code, this.context);
         return await this.engine.hook(topic, signalInputData, status, code);
     }
+    /**
+     * The signal activity will hook all paused jobs that share the same job key.
+     */
     async hookAll() {
+        //prep 1) generate `input signal data` (essentially the webhook payload)
         const signalInputData = this.mapSignalData();
+        //prep 2) generate data that resolves the job key (per the YAML config)
         const keyResolverData = this.mapResolverData();
         if (this.config.scrub) {
+            //self-clean the indexes upon use if configured
             keyResolverData.scrub = true;
         }
+        //prep 3) jobKeys can contain multiple indexes (per the YAML config)
         const key_name = pipe_1.Pipe.resolve(this.config.key_name, this.context);
         const key_value = pipe_1.Pipe.resolve(this.config.key_value, this.context);
         const indexQueryFacets = [`${key_name}:${key_value}`];
+        //execute: `hookAll` will now resume all paused jobs that share the same job key
         return await this.engine.hookAll(this.config.topic, signalInputData, keyResolverData, indexQueryFacets);
     }
 }

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

@@ -21,6 +21,10 @@ declare class Trigger extends Activity {
     resolveJobId(context: Partial<JobState>): string;
     resolveJobKey(context: Partial<JobState>): string;
     setStateNX(): Promise<void>;
+    /**
+     * Registers this job as a dependent of the parent job; when the
+     * parent job is interrupted, this job will be interrupted
+     */
     registerJobDependency(multi?: RedisMulti): Promise<void>;
     setStats(multi?: RedisMulti): Promise<void>;
 }

package/build/services/activities/trigger.js

@@ -33,6 +33,8 @@ class Trigger extends activity_1.Activity {
             await this.setStats(multi);
             await this.registerJobDependency(multi);
             await multi.exec();
+            //if the parent (spawner) chose not to await,
+            // emit the job_id as the data payload { job_id }
             this.execAdjacentParent();
             telemetry.mapActivityAttributes();
             const jobStatus = Number(this.context.metadata.js);
@@ -160,7 +162,7 @@ class Trigger extends activity_1.Activity {
             },
         };
         this.context['$self'] = this.context[this.metadata.aid];
-        this.context['$job'] = this.context;
+        this.context['$job'] = this.context; //NEVER call STRINGIFY! (circular)
     }
     bindJobMetadataPaths() {
         return serializer_1.MDATA_SYMBOLS.JOB.KEYS.map((key) => `metadata/${key}`);
@@ -188,6 +190,10 @@ class Trigger extends activity_1.Activity {
             throw new errors_1.DuplicateJobError(jobId);
         }
     }
+    /**
+     * Registers this job as a dependent of the parent job; when the
+     * parent job is interrupted, this job will be interrupted
+     */
     async registerJobDependency(multi) {
         const depKey = this.config.stats?.parent ?? this.context.metadata.pj;
         let resolvedDepKey = depKey ? pipe_1.Pipe.resolve(depKey, this.context) : '';

package/build/services/activities/worker.js

@@ -11,6 +11,7 @@ class Worker 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('worker-process', { jid: this.context.metadata.jid, gid: this.context.metadata.gid, aid: this.metadata.aid });
         let telemetry;
@@ -19,12 +20,15 @@ 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
             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/collator/index.d.ts

@@ -6,13 +6,40 @@ import { Activity } from '../activities/activity';
 import { Cycle } from '../activities/cycle';
 declare class CollatorService {
     static targetLength: number;
+    /**
+     * Upon re/entry, verify that the job status is active
+     */
     static assertJobActive(status: number, jobId: string, activityId: string): void;
+    /**
+     * 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>;
+    /**
+     * 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?
+     */
     static notarizeReentry(activity: Activity, guid: string, multi?: RedisMulti): Promise<number>;
     static notarizeContinuation(activity: Activity, multi?: RedisMulti): Promise<number>;
     static notarizeCompletion(activity: Activity, multi?: RedisMulti): Promise<number>;
@@ -21,13 +48,56 @@ declare class CollatorService {
     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)
+     */
     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
+     */
     static getSeed(): string;
+    /**
+     * All trigger activities are assigned a status seed in a completed state
+     */
     static getTriggerSeed(): string;
+    /**
+     * entry point for compiler-type activities. This is called by the compiler
+     * to bind the sorted activity IDs to the trigger activity. These are then used
+     * at runtime by the activities to track job/activity status.
+     * @param graphs
+     */
     static compile(graphs: HotMeshGraph[]): void;
+    /**
+     * binds the ancestor array to each activity.
+     * Used in conjunction with the dimensional
+     *  address (dad). If dad is `,0,1,0,0` and the
+     * ancestor array is `['t1', 'a1', 'a2']` for
+     * activity 'a3', then the SAVED DAD
+     * will always have the trailing
+     * 0's removed. This ensures that the addressing
+     * remains consistent even if the graph changes.
+     *   id    DAD           SAVED DAD
+     * * t1 => ,0        =>  [empty]
+     * * a1 => ,0,1      =>  ,0,1
+     * * a2 => ,0,1,0    =>  ,0,1
+     * * a3 => ,0,1,0,0  =>  ,0,1
+     *
+     */
     static bindAncestorArray(graphs: HotMeshGraph[]): void;
+    /**
+     * All activities exist on a dimensional plane. Zero
+     * is the default. A value of
+     * `AxY,0,0,0,0,1,0,0` would reflect that
+     * an ancestor activity was dimensionalized beyond
+     * the default.
+     */
     static getDimensionalSeed(index?: number): string;
 }
 export { CollatorService };

package/build/services/collator/index.js

@@ -4,11 +4,20 @@ exports.CollatorService = void 0;
 const errors_1 = require("../../modules/errors");
 const collator_1 = require("../../types/collator");
 class CollatorService {
+    /**
+     * Upon re/entry, verify that the job status is active
+     */
     static assertJobActive(status, jobId, activityId) {
         if (status <= 0) {
             throw new errors_1.InactiveJobError(jobId, status, activityId);
         }
     }
+    /**
+     * 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;
         if (isEntry && dad && activity.leg === 2) {
@@ -16,37 +25,62 @@ class CollatorService {
         }
         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(',');
+        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);
         this.verifyInteger(amount, 1, 'enter');
         return amount;
     }
     ;
     static async authorizeReentry(activity, multi) {
+        //set second digit to 8, allowing for re-entry
+        //decrement by -10_000_000_000_000
         const amount = await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, -10000000000000, this.getDimensionalAddress(activity), multi);
         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
+        //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);
     }
     ;
+    /**
+     * 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?
+     */
     static async notarizeReentry(activity, guid, multi) {
         const jid = activity.context.metadata.jid;
         const localMulti = multi || activity.store.getMulti();
+        //increment by 1_000_000 (indicates re-entry and is used to drive the 'dimensional address' for adjacent activities (minus 1))
         await activity.store.collate(jid, activity.metadata.aid, 1000000, this.getDimensionalAddress(activity, true), localMulti);
         await activity.store.collateSynthetic(jid, guid, 1000000, localMulti);
         const [_amountConcrete, _amountSynthetic] = await localMulti.exec();
@@ -58,10 +92,13 @@ class CollatorService {
     }
     ;
     static async notarizeContinuation(activity, multi) {
+        //keep open; actualize the leg2 dimension (+1)
         return await activity.store.collate(activity.context.metadata.jid, activity.metadata.aid, 1, this.getDimensionalAddress(activity), multi);
     }
     ;
     static async notarizeCompletion(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);
     }
@@ -90,6 +127,7 @@ class CollatorService {
         return this.getDigitAtIndex(num, 2) < 9;
     }
     static isPrimed(amount, leg) {
+        //activity entry is not allowed if paths not properly pre-set
         if (leg == 1) {
             return amount != -100000000000000;
         }
@@ -98,13 +136,23 @@ class CollatorService {
                 this.getDigitAtIndex(amount, 1) < 9;
         }
     }
+    /**
+     * 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)
+     */
     static verifySyntheticInteger(amount) {
         const samount = amount.toString();
         const isCompletedValue = parseInt(samount[samount.length - 1], 10);
         if (isCompletedValue > 0) {
+            //already done error (ack/delete clearly failed; this is a duplicate)
             throw new errors_1.CollationError(amount, 2, 'enter', collator_1.CollationFaultType.INACTIVE);
         }
         else if (amount >= 2000000) {
+            //duplicate synthetic key (todo: need to resolve/fix this!!)
             throw new errors_1.CollationError(amount, 2, 'enter', collator_1.CollationFaultType.DUPLICATE);
         }
     }
@@ -142,6 +190,11 @@ class CollatorService {
         }
     }
     static getDimensionsById(ancestors, dad) {
+        //ancestors is an ordered list of all ancestors, starting with the trigger (['t1', 'a1', 'a2'])
+        //dad is the dimensional address of the ancestors list (',0,5,3')
+        //loop through the ancestors list and create a map of the ancestor to the dimensional address.
+        //return { 't1': ',0', 'a1': ',0,5', 'a1': ',0,5,3', $ADJACENT: ',0,5,3,0' };
+        // `adjacent` is a special key that is used to track the dimensional address of adjacent activities
         const map = { '$ADJACENT': `${dad},0` };
         let dadStr = dad;
         ancestors.reverse().forEach((ancestor) => {
@@ -150,15 +203,43 @@ class CollatorService {
         });
         return map;
     }
+    /**
+     * All non-trigger activities are assigned a status seed by their parent
+     */
     static getSeed() {
         return '999000000000000';
     }
+    /**
+     * All trigger activities are assigned a status seed in a completed state
+     */
     static getTriggerSeed() {
         return '888000001000001';
     }
+    /**
+     * entry point for compiler-type activities. This is called by the compiler
+     * to bind the sorted activity IDs to the trigger activity. These are then used
+     * at runtime by the activities to track job/activity status.
+     * @param graphs
+     */
     static compile(graphs) {
         CollatorService.bindAncestorArray(graphs);
     }
+    /**
+     * binds the ancestor array to each activity.
+     * Used in conjunction with the dimensional
+     *  address (dad). If dad is `,0,1,0,0` and the
+     * ancestor array is `['t1', 'a1', 'a2']` for
+     * activity 'a3', then the SAVED DAD
+     * will always have the trailing
+     * 0's removed. This ensures that the addressing
+     * remains consistent even if the graph changes.
+     *   id    DAD           SAVED DAD
+     * * t1 => ,0        =>  [empty]
+     * * a1 => ,0,1      =>  ,0,1
+     * * a2 => ,0,1,0    =>  ,0,1
+     * * a3 => ,0,1,0,0  =>  ,0,1
+     *
+     */
     static bindAncestorArray(graphs) {
         graphs.forEach((graph) => {
             const ancestors = {};
@@ -174,12 +255,21 @@ class CollatorService {
                     dfs(transition.to, [...parentList, node]);
                 });
             };
+            // Start the DFS traversal
             dfs(startingNode, []);
         });
     }
+    /**
+     * All activities exist on a dimensional plane. Zero
+     * is the default. A value of
+     * `AxY,0,0,0,0,1,0,0` would reflect that
+     * an ancestor activity was dimensionalized beyond
+     * the default.
+     */
     static getDimensionalSeed(index = 0) {
         return `,${index}`;
     }
 }
 exports.CollatorService = CollatorService;
+//max int digit count that supports `hincrby`
 CollatorService.targetLength = 15;