@hotmeshio/hotmesh 0.0.52 → 0.0.54

package/build/types/stream.d.ts

@@ -1,18 +1,38 @@
+/** Represents a policy for retrying stream operations based on error codes */
 export interface StreamRetryPolicy {
-    [key: string]: [number, 'x'];
+    /**
+     * Key is error code, value is the retry profile.
+     * Tuple contains: [max retry count, retry type].
+     * 'x' denotes exponential backoff (default). Only 10, 100, 1000, 10000 are allowed retry intervals.
+     */
+    [key: string]: [number, 'x'?];
 }
+/** A 3-digit status code representing the outcome of a stream operation */
 export type StreamCode = number;
+/** Describes the structure of a stream error */
 export type StreamError = {
+    /** Descriptive message of the error */
     message: string;
+    /** Numeric code corresponding to the type of error */
     code: number;
+    /** Optional job identifier, used when communicating errors externally */
     job_id?: string;
+    /** Stack trace of the error if unhandled */
     stack?: string;
+    /** Name of the error if unhandled */
     name?: string;
+    /** Custom user-defined error details */
     error?: Record<string, unknown>;
+    /** True if originating via a standard transition message with an `error` status */
+    is_stream_error?: boolean;
 };
+/** Enumerated status values for stream operations */
 export declare enum StreamStatus {
+    /** Indicates successful completion of the stream operation */
     SUCCESS = "success",
+    /** Indicates an error occurred during the stream operation */
     ERROR = "error",
+    /** Indicates the stream operation is still pending */
     PENDING = "pending"
 }
 export declare enum StreamDataType {
@@ -26,27 +46,51 @@ export declare enum StreamDataType {
     SIGNAL = "signal",
     INTERRUPT = "interrupt"
 }
+/** Defines the structure of stream data used when passing stream messages (transitions) */
 export interface StreamData {
+    /** Metadata associated with the stream data */
     metadata: {
+        /** Globally unique identifier for the StreamData message to distinguish `retries` from new 'reentry/cycles' */
         guid: string;
+        /** Workflow/job topic */
         topic?: string;
+        /** Workflow/job ID */
         jid?: string;
+        /** Workflow Generational ID (internal GUID) */
         gid?: string;
+        /** Dimensional address indicating the message routing specifics */
         dad?: string;
+        /** Activity ID */
         aid: string;
+        /** OpenTelemetry Trace identifier */
         trc?: string;
+        /** OpenTelemetry Span identifier */
         spn?: string;
+        /** Current try count, used for retry logic */
         try?: number;
+        /**
+         * Indicates if the message should wait for a response.
+         * If explicitly false, the connection is severed immediately
+         * upon verifying (and returning) the Job ID.
+         */
         await?: boolean;
     };
+    /** Type of the data being streamed, optional */
     type?: StreamDataType;
+    /** Actual data being transmitted as a record of key-value pairs */
     data: Record<string, unknown>;
+    /** Policies related to retry logic, optional */
     policies?: {
         retry?: StreamRetryPolicy;
     };
+    /** Status of the stream, default assumed as 'success' */
     status?: StreamStatus;
+    /** HTTP-like status code for the stream, default assumed as 200 */
     code?: number;
+    /** Error stack trace */
+    stack?: string;
 }
+/** Extends StreamData for responses, allowing for inheritance of the base properties */
 export interface StreamDataResponse extends StreamData {
 }
 export declare enum StreamRole {
@@ -54,19 +98,35 @@ export declare enum StreamRole {
     ENGINE = "engine",
     SYSTEM = "system"
 }
+/**
+ * Represents a type for messages that have been reclaimed from a stream.
+ * Each item is a tuple containing a messageId and its details.
+ */
 export type ReclaimedMessageType = [
+    /** The stream ID, typically formatted as `<timestamp>-<count>` */
     messageId: string,
+    /** Details of the message, consisting of a key and its value */
     details: [
+        /** Key is always 'message' */
         key: string,
+        /** Value is a stringified representation of StreamData */
         value: string
     ]
 ][];
+/** Configuration parameters for a stream */
 export type StreamConfig = {
+    /** Namespace under which the stream operates */
     namespace: string;
+    /** Application identifier */
     appId: string;
+    /** Globally unique identifier for the stream */
     guid: string;
+    /** Role associated with the stream */
     role: StreamRole;
+    /** Optional topic for the stream */
     topic?: string;
+    /** Delay before a message can be reclaimed, defaults to 60,000 milliseconds */
     reclaimDelay?: number;
+    /** Maximum number of reclaims allowed, defaults to 3. Values greater throw an error */
     reclaimCount?: number;
 };

package/build/types/stream.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamRole = exports.StreamDataType = exports.StreamStatus = void 0;
+/** Enumerated status values for stream operations */
 var StreamStatus;
 (function (StreamStatus) {
+    /** Indicates successful completion of the stream operation */
     StreamStatus["SUCCESS"] = "success";
+    /** Indicates an error occurred during the stream operation */
     StreamStatus["ERROR"] = "error";
+    /** Indicates the stream operation is still pending */
     StreamStatus["PENDING"] = "pending";
 })(StreamStatus = exports.StreamStatus || (exports.StreamStatus = {}));
 var StreamDataType;

package/index.ts

@@ -1,7 +1,6 @@
 import { Durable } from './services/durable';
-import { MeshOSService as MeshOS } from './services/durable/meshos';
 import { HotMeshService as HotMesh } from './services/hotmesh';
 import { HotMeshConfig } from './types/hotmesh';
 
-export { Durable, HotMesh, HotMeshConfig, MeshOS };
+export { Durable, HotMesh, HotMeshConfig };
 export * as Types from './types';

package/modules/enums.ts

@@ -3,7 +3,7 @@ import { LogLevel } from "../types/logger";
 // HOTMESH SYSTEM
 export const HMSH_LOGLEVEL = process.env.HMSH_LOGLEVEL as LogLevel || 'info';
 
-// STATUS CODES AND MESSAGES
+// HOTMESH STATUS CODES
 export const HMSH_CODE_SUCCESS = 200;
 export const HMSH_CODE_PENDING = 202;
 export const HMSH_CODE_NOTFOUND = 404;
@@ -11,15 +11,18 @@ export const HMSH_CODE_INTERRUPT = 410;
 export const HMSH_CODE_UNKNOWN = 500;
 export const HMSH_CODE_TIMEOUT = 504;
 export const HMSH_CODE_UNACKED = 999;
-
-export const HMSH_CODE_DURABLE_SLEEPFOR = 592;
-export const HMSH_CODE_DURABLE_INCOMPLETE = 593;
-export const HMSH_CODE_DURABLE_WAITFOR = 594;
+// DURABLE STATUS CODES
+export const HMSH_CODE_DURABLE_SLEEP = 588;
+export const HMSH_CODE_DURABLE_ALL = 589;
+export const HMSH_CODE_DURABLE_CHILD = 590;
+export const HMSH_CODE_DURABLE_PROXY = 591;
+export const HMSH_CODE_DURABLE_WAIT = 595;
 export const HMSH_CODE_DURABLE_TIMEOUT = 596;
 export const HMSH_CODE_DURABLE_MAXED = 597;
 export const HMSH_CODE_DURABLE_FATAL = 598;
 export const HMSH_CODE_DURABLE_RETRYABLE = 599;
 
+// HOTMESH MESSAGES
 export const HMSH_STATUS_UNKNOWN = 'unknown';
 
 // QUORUM
@@ -36,8 +39,13 @@ export const HMSH_MAX_RETRIES = parseInt(process.env.HMSH_MAX_RETRIES, 10) || 3;
 export const HMSH_MAX_TIMEOUT_MS = parseInt(process.env.HMSH_MAX_TIMEOUT_MS, 10) || 60000;
 export const HMSH_GRADUATED_INTERVAL_MS = parseInt(process.env.HMSH_GRADUATED_INTERVAL_MS, 10) || 5000;
 
-const BASE_BLOCK_DURATION = 10000; // Modified for clarity
-const TEST_BLOCK_DURATION = 1000; // Modified for clarity
+// DURABLE
+export const HMSH_DURABLE_MAX_ATTEMPTS =  3;
+export const HMSH_DURABLE_MAX_INTERVAL = '120s';
+export const HMSH_DURABLE_EXP_BACKOFF = 10;
+
+const BASE_BLOCK_DURATION = 10000;
+const TEST_BLOCK_DURATION = 1000;
 export const HMSH_BLOCK_TIME_MS = process.env.HMSH_BLOCK_TIME_MS ? parseInt(process.env.HMSH_BLOCK_TIME_MS, 10) : (process.env.NODE_ENV === 'test' ? TEST_BLOCK_DURATION : BASE_BLOCK_DURATION);
 
 export const HMSH_XCLAIM_DELAY_MS = parseInt(process.env.HMSH_XCLAIM_DELAY_MS, 10) || 1000 * 60;
@@ -48,7 +56,7 @@ export const HMSH_XPENDING_COUNT = parseInt(process.env.HMSH_XPENDING_COUNT, 10)
 export const HMSH_EXPIRE_DURATION = parseInt(process.env.HMSH_EXPIRE_DURATION, 10) || 1;
 
 const BASE_FIDELITY_SECONDS = 5;
-const TEST_FIDELITY_SECONDS = 5;
+const TEST_FIDELITY_SECONDS = 1;
 export const HMSH_FIDELITY_SECONDS = process.env.HMSH_FIDELITY_SECONDS ? parseInt(process.env.HMSH_FIDELITY_SECONDS, 10) : (process.env.NODE_ENV === 'test' ? TEST_FIDELITY_SECONDS : BASE_FIDELITY_SECONDS);
 
 export const HMSH_SCOUT_INTERVAL_SECONDS = parseInt(process.env.HMSH_SCOUT_INTERVAL_SECONDS, 10) || 60;

package/modules/errors.ts

@@ -1,14 +1,22 @@
-import { ActivityDuplex } from "../types/activity";
-import { CollationFaultType, CollationStage } from "../types/collator";
 import {
   HMSH_CODE_DURABLE_MAXED,
   HMSH_CODE_DURABLE_TIMEOUT,
   HMSH_CODE_DURABLE_FATAL,
-  HMSH_CODE_DURABLE_INCOMPLETE,
   HMSH_CODE_NOTFOUND,
   HMSH_CODE_DURABLE_RETRYABLE,
-  HMSH_CODE_DURABLE_SLEEPFOR,
-  HMSH_CODE_DURABLE_WAITFOR } from "./enums";
+  HMSH_CODE_DURABLE_WAIT,
+  HMSH_CODE_DURABLE_PROXY,
+  HMSH_CODE_DURABLE_CHILD,
+  HMSH_CODE_DURABLE_ALL,
+  HMSH_CODE_DURABLE_SLEEP } from "./enums";
+import { ActivityDuplex } from "../types/activity";
+import { CollationFaultType, CollationStage } from "../types/collator";
+import {
+  DurableChildErrorType,
+  DurableProxyErrorType,
+  DurableSleepErrorType,
+  DurableWaitForAllErrorType,
+  DurableWaitForErrorType } from "../types/error";
 
 class GetStateError extends Error {
   jobId: string;
@@ -24,65 +32,158 @@ class SetStateError extends Error {
   }
 }
 
-//thrown when a signal set is incomplete but already configured
-//if a waitFor set has 'n' items, this can be thrown `n - 1` times
-class DurableIncompleteSignalError extends Error {
+class DurableWaitForError extends Error {
   code: number;
-  constructor(message: string) {
-    super(message);
-    this.code = HMSH_CODE_DURABLE_INCOMPLETE;
+  signalId: string;
+  workflowId: string;
+  index: number;
+  workflowDimension: string; //hook workflowDimension (e.g., ',0,1,0') (use empty string for `null`)
+  constructor(params: DurableWaitForErrorType) {
+    super(`WaitFor Interruption`);
+    this.signalId = params.signalId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_WAIT;
   }
 }
 
-//the original waitFor error that is thrown for a new signal set
-class DurableWaitForSignalError extends Error {
+class DurableProxyError extends Error {
+  activityName: string;
+  arguments: string[];
+  backoffCoefficient: number;
   code: number;
-  signals: {signal: string, index: number}[]; //signal id and execution order in the workflow
-  constructor(message: string, signals: {signal: string, index: number}[]) {
-    super(message);
-    this.signals = signals;
-    this.code = HMSH_CODE_DURABLE_WAITFOR;
+  index: number;
+  maximumAttempts: number;
+  maximumInterval: number;
+  originJobId: string | null;
+  parentWorkflowId: string;
+  workflowDimension: string;
+  workflowId: string;
+  workflowTopic: string;
+  constructor(params: DurableProxyErrorType) {
+    super(`ProxyActivity Interruption`);
+    this.arguments = params.arguments;
+    this.workflowId = params.workflowId;
+    this.workflowTopic = params.workflowTopic;
+    this.parentWorkflowId = params.parentWorkflowId;
+    this.originJobId = params.originJobId;
+    this.index = params.index;
+    this.activityName = params.activityName;
+    this.workflowDimension = params.workflowDimension;
+    this.backoffCoefficient = params.backoffCoefficient;
+    this.maximumAttempts = params.maximumAttempts;
+    this.maximumInterval = params.maximumInterval;
+    this.code = HMSH_CODE_DURABLE_PROXY;
   }
 }
 
-class DurableSleepForError extends Error {
+class DurableChildError extends Error {
+  await: boolean;
+  arguments: string[];
+  backoffCoefficient: number;
+  code: number;
+  workflowDimension: string;
+  index: number;
+  maximumAttempts: number;
+  maximumInterval: number;
+  originJobId: string | null;
+  parentWorkflowId: string;
+  workflowId: string;
+  workflowTopic: string;
+  constructor(params: DurableChildErrorType) {
+    super(`ExecChild Interruption`);
+    this.arguments = params.arguments;
+    this.workflowId = params.workflowId;
+    this.workflowTopic = params.workflowTopic;
+    this.parentWorkflowId = params.parentWorkflowId;
+    this.originJobId = params.originJobId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_CHILD;
+    this.await = params.await;
+    this.backoffCoefficient = params.backoffCoefficient;
+    this.maximumAttempts = params.maximumAttempts;
+    this.maximumInterval = params.maximumInterval;
+  }
+}
+
+class DurableWaitForAllError extends Error {
+  items: any[];
+  code: number;
+  workflowDimension: string;
+  size: number;
+  index: number;
+  originJobId: string | null;
+  parentWorkflowId: string;
+  workflowId: string;
+  workflowTopic: string;
+  constructor(params: DurableWaitForAllErrorType) {
+    super(`Collation Interruption`);
+    this.items = params.items;
+    this.size = params.size;
+    this.workflowId = params.workflowId;
+    this.workflowTopic = params.workflowTopic;
+    this.parentWorkflowId = params.parentWorkflowId;
+    this.originJobId = params.originJobId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_ALL;
+  }
+}
+
+class DurableSleepError extends Error {
+  workflowId: string;
   code: number;
   duration: number; //seconds
-  index: number;    //execution order in the workflow
-  dimension: string; //hook dimension (e.g., ',0,1,0') (uses empty string for `null`)
-  constructor(message: string, duration: number, index: number, dimension: string) {
-    super(message);
-    this.duration = duration;
-    this.index = index;
-    this.dimension = dimension;
-    this.code = HMSH_CODE_DURABLE_SLEEPFOR;
+  index: number;
+  workflowDimension: string; //empty string for null
+  constructor(params: DurableSleepErrorType) {
+    super(`SleepFor Interruption`);
+    this.duration = params.duration;
+    this.workflowId = params.workflowId;
+    this.index = params.index;
+    this.workflowDimension = params.workflowDimension;
+    this.code = HMSH_CODE_DURABLE_SLEEP;
   }
 }
+
 class DurableTimeoutError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stack?: string) {
     super(message);
+    if (this.stack) {
+      this.stack = stack;
+    }
     this.code = HMSH_CODE_DURABLE_TIMEOUT;
   }
 }
 class DurableMaxedError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stackTrace?: string) {
     super(message);
+    if (stackTrace) {
+      this.stack = stackTrace;
+    }
     this.code = HMSH_CODE_DURABLE_MAXED;
   }
 }
 class DurableFatalError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stackTrace?: string) {
     super(message);
+    if (stackTrace) {
+      this.stack = stackTrace;
+    }
     this.code = HMSH_CODE_DURABLE_FATAL;
   }
 }
 class DurableRetryError extends Error {
   code: number;
-  constructor(message: string) {
+  constructor(message: string, stackTrace?: string) {
     super(message);
+    if (stackTrace) {
+      this.stack = stackTrace;
+    }
     this.code = HMSH_CODE_DURABLE_RETRYABLE;
   }
 }
@@ -100,8 +201,10 @@ class RegisterTimeoutError extends Error {
 }
 
 class DuplicateJobError extends Error {
+  jobId: string;
   constructor(jobId: string) {
     super("Duplicate job");
+    this.jobId = jobId;
     this.message = `Duplicate job: ${jobId}`;
   }
 }
@@ -157,13 +260,15 @@ class CollationError extends Error {
 
 export {
   CollationError,
+  DurableChildError,
   DurableFatalError,
-  DurableIncompleteSignalError,
   DurableMaxedError,
+  DurableProxyError,
   DurableRetryError,
-  DurableSleepForError,
+  DurableSleepError,
   DurableTimeoutError,
-  DurableWaitForSignalError,
+  DurableWaitForAllError,
+  DurableWaitForError,
   DuplicateJobError,
   ExecActivityError,
   GenerationalError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "description": "Unbreakable Workflows",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -21,13 +21,16 @@
     "start": "ts-node src/index.ts",
     "test": "NODE_ENV=test jest --detectOpenHandles --forceExit --verbose",
     "test:hmsh": "NODE_ENV=test jest ./tests/functional/index.test.ts --detectOpenHandles --verbose",
+    "test:pipe": "NODE_ENV=test jest ./tests/unit/services/pipe/index.test.ts --detectOpenHandles --forceExit --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:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.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",
+    "test:functional": "NODE_ENV=test jest ./tests/functional/*/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:emit": "NODE_ENV=test jest ./tests/functional/emit/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:await": "NODE_ENV=test jest ./tests/functional/awaiter/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:hook": "NODE_ENV=test jest ./tests/functional/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:signal": "NODE_ENV=test jest ./tests/functional/signal/index.test.ts --detectOpenHandles --forceExit --verbose",
@@ -46,13 +49,15 @@
     "test:sub:redis": "NODE_ENV=test jest ./tests/functional/sub/clients/redis.test.ts --detectOpenHandles --forceExit --verbose",
     "test:sub:ioredis": "NODE_ENV=test jest ./tests/functional/sub/clients/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable": "NODE_ENV=test jest ./tests/durable/*/index.test.ts --detectOpenHandles --forceExit --verbose",
-    "test:durable:meshos": "NODE_ENV=test jest ./tests/durable/meshos/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:durable:basic": "NODE_ENV=test jest ./tests/durable/basic/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:durable:collision": "NODE_ENV=test jest ./tests/durable/collision/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:hello": "NODE_ENV=test jest ./tests/durable/helloworld/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:interrupt": "NODE_ENV=test jest ./tests/durable/interrupt/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:goodbye": "NODE_ENV=test jest ./tests/durable/goodbye/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:hook": "NODE_ENV=test jest ./tests/durable/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:retry": "NODE_ENV=test jest ./tests/durable/retry/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:fatal": "NODE_ENV=test jest ./tests/durable/fatal/index.test.ts --detectOpenHandles --forceExit --verbose",
+    "test:durable:unknown": "NODE_ENV=test jest ./tests/durable/unknown/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:sleep": "NODE_ENV=test jest ./tests/durable/sleep/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:signal": "NODE_ENV=test jest ./tests/durable/signal/index.test.ts --detectOpenHandles --forceExit --verbose",
     "test:durable:loopactivity": "NODE_ENV=test jest ./tests/durable/loopactivity/index.test.ts --detectOpenHandles --forceExit --verbose",

package/services/activities/activity.ts

@@ -143,19 +143,19 @@ class Activity {
       this.transitionAdjacent(multiResponse, telemetry);
     } catch (error) {
       if (error instanceof CollationError) {
-        this.logger.info('process-event-inactive-error', { error });
+        this.logger.info('process-event-inactive-error', { ...error });
         return;
       } else if (error instanceof InactiveJobError) {
-        this.logger.info('process-event-inactive-job-error', { error });
+        this.logger.info('process-event-inactive-job-error', { ...error });
         return;
       } else if (error instanceof GenerationalError) {
-        this.logger.info('process-event-generational-job-error', { error });
+        this.logger.info('process-event-generational-job-error', { ...error });
         return;
       } else if (error instanceof GetStateError) {
-        this.logger.info('process-event-get-job-error', { error });
+        this.logger.info('process-event-get-job-error', {  ...error  });
         return;
       }
-      this.logger.error('activity-process-event-error', { error });
+      this.logger.error('activity-process-event-error', { ...error, message: error.message, stack: error.stack, name: error.name });
       telemetry && telemetry.setActivityError(error.message);
       throw error;
     } finally {
@@ -191,6 +191,10 @@ class Activity {
   async processError(telemetry: TelemetryService, type: string): Promise<MultiResponseFlags> {
     this.bindActivityError(this.data);
     this.adjacencyList = await this.filterAdjacent();
+    if (!this.adjacencyList.length) {
+      this.bindJobError(this.data);
+    }
+    this.mapJobData();
     const multi = this.store.getMulti();
     await this.setState(multi);
     await CollatorService.notarizeCompletion(this, multi);
@@ -205,7 +209,7 @@ class Activity {
     const attrs: StringScalarType = { '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) {
+    if (messageIds?.length) {
       attrs['app.activity.mids'] = messageIds.join(',')
     }
     telemetry.setActivityAttributes(attrs);
@@ -223,7 +227,30 @@ class Activity {
   mapJobData(): void {
     if(this.config.job?.maps) {
       const mapper = new MapperService(this.config.job.maps, this.context);
-      this.context.data = mapper.mapRules();
+      const output = mapper.mapRules();
+      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))) {
+              const left = key.substring(0, f1);
+              output[left] = output[key];
+              delete output[key];
+            } else if (amount === '-' || amount === '_') {
+              const obj = output[key];
+              Object.keys(obj).forEach((newKey) => {
+                output[newKey] = obj[newKey];
+              });
+            }
+          }
+        }
+      }
+      this.context.data = output;
     }
   }
 
@@ -249,10 +276,22 @@ class Activity {
     //set timeout in support of hook and/or duplex
   }
 
+  /**
+   * Any StreamMessage with a status of ERROR is bound to the activity
+   */
   bindActivityError(data: Record<string, unknown>): void {
-    //todo: map activity error data into the job error (if defined)
-    //      map job status via: (500: [3**, 4**, 5**], 202: [$pending])
-    this.context.metadata.err = JSON.stringify(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: Record<string, unknown>): void {
+    this.context.metadata.err = JSON.stringify({ ...data, is_stream_error: true });
   }
 
   async getTriggerConfig(): Promise<ActivityType> {
@@ -322,9 +361,9 @@ class Activity {
     if (this.status === StreamStatus.ERROR) {
       self.output.metadata.err = JSON.stringify(this.data);
     }
-    //todo: verify leg2 never overwrites leg1 `ac`
-    self.output.metadata.ac = 
-      self.output.metadata.au = formatISODate(new Date());
+    const ts = formatISODate(new Date());
+    self.output.metadata.ac = ts;
+    self.output.metadata.au = ts;
     self.output.metadata.atp = this.config.type;
     if (this.config.subtype) {
       self.output.metadata.stp = this.config.subtype;
@@ -344,6 +383,11 @@ class Activity {
         state[path] = value;
       }
     }
+    for (let key in this.context?.data ?? {}) {
+      if (key.startsWith('-') || key.startsWith('_')) {
+        state[key] = this.context.data[key];
+      }
+    }
     TelemetryService.bindJobTelemetryToState(state, this.config, this.context);
   }
 
@@ -398,7 +442,7 @@ class Activity {
     let { dad, jid } = this.context.metadata;
     const dIds = 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);
+    const [state, _status] = await this.store.getState(jid, consumes, dIds);
     this.context = restoreHierarchy(state) as JobState;
     this.assertGenerationalId(this.context?.metadata?.gid, gid);
     this.initDimensionalAddress(dad);
@@ -443,6 +487,11 @@ class Activity {
     if (!self.hook) {
       self.hook = { };
     }
+    if (!self.output.metadata) {
+      self.output.metadata = { };
+    }
+    //prebind the updated timestamp (mappings need the time)
+    self.output.metadata.au = formatISODate(new Date());
     context['$self'] = self;
     context['$job'] = context; //NEVER call STRINGIFY! (now circular)
     return context as JobState;