@hotmeshio/hotmesh 0.13.0 → 0.14.0

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

@@ -0,0 +1,116 @@
+import { EngineService } from '../../engine';
+import { ILogger } from '../../logger';
+import { StoreService } from '../../store';
+import { TelemetryService } from '../../telemetry';
+import { ActivityData, ActivityLeg, ActivityMetadata, ActivityType } from '../../../types/activity';
+import { ProviderClient, ProviderTransaction, TransactionResultList } from '../../../types/provider';
+import { JobState, JobStatus } from '../../../types/job';
+import { StringAnyType } from '../../../types/serializer';
+import { StreamCode, StreamData, StreamStatus } from '../../../types/stream';
+/**
+ * Base class for every node in the workflow DAG.
+ *
+ * An activity's lifecycle flows top-to-bottom through this file:
+ * enter → load state → map data → persist → transition → complete.
+ *
+ * Each section delegates to a purpose-specific module inside `activity/`.
+ * Open the module when you need implementation detail; read this file
+ * when you need the big picture.
+ */
+declare class Activity {
+    config: ActivityType;
+    data: ActivityData;
+    hook: ActivityData;
+    metadata: ActivityMetadata;
+    /** @hidden */
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    engine: EngineService;
+    logger: ILogger;
+    context: JobState;
+    status: StreamStatus;
+    code: StreamCode;
+    leg: ActivityLeg;
+    adjacencyList: StreamData[];
+    adjacentIndex: number;
+    guidLedger: number;
+    constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
+    /** Leg 1 entry for duplex activities (Worker, Await, Cycle) */
+    verifyEntry(): Promise<void>;
+    /** Leg 2 re-entry for duplex activities; returns the activity ledger */
+    verifyReentry(): Promise<number>;
+    /** Leg 1 entry for Category B (Hook passthrough, Signal, Interrupt-target).
+     *  Returns true when resuming from a prior crash (Leg1 already committed). */
+    verifyLeg1Entry(): Promise<boolean>;
+    /** Load job state from the store into `this.context` */
+    getState(): Promise<void>;
+    /** Bootstrap $self, $job refs and output.metadata.au timestamp */
+    initSelf(ctx: StringAnyType): JobState;
+    /** Resolve expire and persistent policies from config */
+    initPolicies(ctx: JobState): void;
+    /** Set the dimensional address for this activity */
+    initDimensionalAddress(dad: string): void;
+    /** Reject stale messages from a prior job generation */
+    assertGenerationalId(jobGID: string, msgGID?: string): void;
+    /** Map data INTO this activity (from other activities' outputs) */
+    mapInputData(): void;
+    /** Transform this activity's own output via output.maps */
+    mapOutputData(): void;
+    /** Promote activity data to the shared job state via job.maps */
+    mapJobData(): void;
+    /** Resolve the Dynamic Activation Control threshold (default: 0) */
+    mapStatusThreshold(): number;
+    /** Stamp job-level `ju` (job_updated) timestamp */
+    bindJobMetadata(): void;
+    /** Stamp activity-level timestamps, type, and subtype */
+    bindActivityMetadata(): void;
+    /** Flatten job-level context paths into store-ready key/values */
+    bindJobState(state: StringAnyType): Promise<void>;
+    /** Flatten activity-level context paths into store-ready key/values */
+    bindActivityState(state: StringAnyType): void;
+    /** Write the dimensional address into the state payload */
+    bindDimensionalAddress(state: StringAnyType): void;
+    /** Attach inbound data (output or hook) to the activity's context slot */
+    bindActivityData(type: 'output' | 'hook'): void;
+    /** Attach an error response to the activity's context slot */
+    bindActivityError(data: Record<string, unknown>): void;
+    /** Promote an unhandled activity error to the job level */
+    bindJobError(data: Record<string, unknown>): void;
+    /** Persist the full activity + job state in a single store call */
+    setState(txn?: ProviderTransaction): Promise<string>;
+    /** Increment/decrement the job semaphore */
+    setStatus(amount: number, txn?: ProviderTransaction): Promise<void | any>;
+    /** Build the list of child activities to transition to */
+    filterAdjacent(): Promise<StreamData[]>;
+    /** Current dimensional address (accounts for cycle offset) */
+    resolveDad(): string;
+    /** Dimensional address for children (appends seed `,0`) */
+    resolveAdjacentDad(): string;
+    /** Did the semaphore reach its threshold? (from transaction results) */
+    resolveThresholdHit(results: TransactionResultList): boolean;
+    /** Extract the job status from the last transaction result */
+    resolveStatus(multi: TransactionResultList): number;
+    /** Should this activity emit to the graph's publishes topic? */
+    shouldEmit(): boolean;
+    /** Should this activity emit completion while keeping the job alive? */
+    shouldPersistJob(): boolean;
+    isJobComplete(s: JobStatus): boolean;
+    jobWasInterrupted(s: JobStatus): boolean;
+    /** Leg 2 protocol: save → spawn → complete (duplex activities) */
+    executeStepProtocol(delta: number, shouldFinalize: boolean): Promise<boolean>;
+    /** Leg 1 protocol: save → spawn → complete (Category B activities) */
+    executeLeg1StepProtocol(delta: number): Promise<boolean>;
+    processEvent(status?: StreamStatus, code?: StreamCode, type?: 'hook' | 'output'): Promise<void>;
+    setLeg(leg: ActivityLeg): void;
+    registerTimeout(): Promise<void>;
+    getJobStatus(): null | number;
+    authorizeEntry(_state: StringAnyType): string[];
+    bindSearchData(_options?: any): void;
+    bindMarkerData(_options?: any): void;
+    /** Job metadata paths to persist (Trigger overrides with full JOB set) */
+    bindJobMetadataPaths(): string[];
+    /** Activity metadata paths to persist (Trigger overrides; leg-aware) */
+    bindActivityMetadataPaths(): string[];
+    getTriggerConfig(): Promise<ActivityType>;
+    handleProcessError(error: Error, telemetry: TelemetryService | undefined, label: string): void;
+}
+export { Activity, ActivityType };

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

@@ -0,0 +1,299 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Activity = void 0;
+const errors_1 = require("../../../modules/errors");
+const stream_1 = require("../../../types/stream");
+const Mapping = __importStar(require("./mapping"));
+const Context = __importStar(require("./context"));
+const State = __importStar(require("./state"));
+const Transition = __importStar(require("./transition"));
+const Verify = __importStar(require("./verify"));
+const Protocol = __importStar(require("./protocol"));
+const Process = __importStar(require("./process"));
+/**
+ * Base class for every node in the workflow DAG.
+ *
+ * An activity's lifecycle flows top-to-bottom through this file:
+ * enter → load state → map data → persist → transition → complete.
+ *
+ * Each section delegates to a purpose-specific module inside `activity/`.
+ * Open the module when you need implementation detail; read this file
+ * when you need the big picture.
+ */
+class Activity {
+    constructor(config, data, metadata, hook, engine, context) {
+        this.status = stream_1.StreamStatus.SUCCESS;
+        this.code = 200;
+        this.adjacentIndex = 0;
+        this.guidLedger = 0;
+        this.config = config;
+        this.data = data;
+        this.metadata = metadata;
+        this.hook = hook;
+        this.engine = engine;
+        this.context = context || { data: {}, metadata: {} };
+        this.logger = engine.logger;
+        this.store = engine.store;
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  1. ENTER — verify this activity is allowed to run
+    //     Guards against stale messages, duplicate deliveries,
+    //     and inactive jobs. Sets the execution leg.
+    //     → see verify.ts
+    // ═════════════════════════════════════════════════════════════════
+    /** Leg 1 entry for duplex activities (Worker, Await, Cycle) */
+    async verifyEntry() {
+        return Verify.verifyEntry(this);
+    }
+    /** Leg 2 re-entry for duplex activities; returns the activity ledger */
+    async verifyReentry() {
+        return Verify.verifyReentry(this);
+    }
+    /** Leg 1 entry for Category B (Hook passthrough, Signal, Interrupt-target).
+     *  Returns true when resuming from a prior crash (Leg1 already committed). */
+    async verifyLeg1Entry() {
+        return Verify.verifyLeg1Entry(this);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  2. LOAD / INITIALIZE — hydrate job state from the store
+    //     Reads the hash, restores the context tree, validates
+    //     the generational ID, and initializes $self / policies.
+    //     → see state.ts (getState) and context.ts
+    // ═════════════════════════════════════════════════════════════════
+    /** Load job state from the store into `this.context` */
+    async getState() {
+        return State.getState(this);
+    }
+    /** Bootstrap $self, $job refs and output.metadata.au timestamp */
+    initSelf(ctx) {
+        return Context.initSelf(this, ctx);
+    }
+    /** Resolve expire and persistent policies from config */
+    initPolicies(ctx) {
+        Context.initPolicies(this, ctx);
+    }
+    /** Set the dimensional address for this activity */
+    initDimensionalAddress(dad) {
+        Context.initDimensionalAddress(this, dad);
+    }
+    /** Reject stale messages from a prior job generation */
+    assertGenerationalId(jobGID, msgGID) {
+        Context.assertGenerationalId(jobGID, msgGID, this.context);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  3. MAP — transform data between activities and the job
+    //     Evaluates @pipe expressions in the YAML `maps` config
+    //     to move data in (input), out (output), and to the job.
+    //     → see mapping.ts
+    // ═════════════════════════════════════════════════════════════════
+    /** Map data INTO this activity (from other activities' outputs) */
+    mapInputData() {
+        Mapping.mapInputData(this);
+    }
+    /** Transform this activity's own output via output.maps */
+    mapOutputData() {
+        Mapping.mapOutputData(this);
+    }
+    /** Promote activity data to the shared job state via job.maps */
+    mapJobData() {
+        Mapping.mapJobData(this);
+    }
+    /** Resolve the Dynamic Activation Control threshold (default: 0) */
+    mapStatusThreshold() {
+        return Mapping.mapStatusThreshold(this);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  4. BIND — prepare context fields for persistence
+    //     Stamps metadata, flattens the context tree into key/value
+    //     pairs, and attaches error or hook data.
+    //     → see state.ts (bind*) and context.ts (bindActivity*)
+    // ═════════════════════════════════════════════════════════════════
+    /** Stamp job-level `ju` (job_updated) timestamp */
+    bindJobMetadata() {
+        State.bindJobMetadata(this);
+    }
+    /** Stamp activity-level timestamps, type, and subtype */
+    bindActivityMetadata() {
+        State.bindActivityMetadata(this);
+    }
+    /** Flatten job-level context paths into store-ready key/values */
+    async bindJobState(state) {
+        return State.bindJobState(this, state);
+    }
+    /** Flatten activity-level context paths into store-ready key/values */
+    bindActivityState(state) {
+        State.bindActivityState(this, state);
+    }
+    /** Write the dimensional address into the state payload */
+    bindDimensionalAddress(state) {
+        State.bindDimensionalAddress(this, state);
+    }
+    /** Attach inbound data (output or hook) to the activity's context slot */
+    bindActivityData(type) {
+        Context.bindActivityData(this, type);
+    }
+    /** Attach an error response to the activity's context slot */
+    bindActivityError(data) {
+        Context.bindActivityError(this, data);
+    }
+    /** Promote an unhandled activity error to the job level */
+    bindJobError(data) {
+        Context.bindJobError(this, data);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  5. PERSIST — write state to the store
+    //     Orchestrates bind → flatten → store.setState in one call.
+    //     Also handles the job semaphore (setStatus).
+    //     → see state.ts
+    // ═════════════════════════════════════════════════════════════════
+    /** Persist the full activity + job state in a single store call */
+    async setState(txn) {
+        return State.setState(this, txn);
+    }
+    /** Increment/decrement the job semaphore */
+    async setStatus(amount, txn) {
+        return State.setStatus(this, amount, txn);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  6. TRANSITION — resolve which children run next
+    //     Evaluates transition rules, checks job completion,
+    //     and builds the adjacency list for the step protocol.
+    //     → see transition.ts and context.ts (resolveDad)
+    // ═════════════════════════════════════════════════════════════════
+    /** Build the list of child activities to transition to */
+    async filterAdjacent() {
+        return Transition.filterAdjacent(this);
+    }
+    /** Current dimensional address (accounts for cycle offset) */
+    resolveDad() {
+        return Context.resolveDad(this);
+    }
+    /** Dimensional address for children (appends seed `,0`) */
+    resolveAdjacentDad() {
+        return Context.resolveAdjacentDad(this);
+    }
+    /** Did the semaphore reach its threshold? (from transaction results) */
+    resolveThresholdHit(results) {
+        return Transition.resolveThresholdHit(results);
+    }
+    /** Extract the job status from the last transaction result */
+    resolveStatus(multi) {
+        return Transition.resolveStatus(multi);
+    }
+    /** Should this activity emit to the graph's publishes topic? */
+    shouldEmit() {
+        return Transition.shouldEmit(this);
+    }
+    /** Should this activity emit completion while keeping the job alive? */
+    shouldPersistJob() {
+        return Transition.shouldPersistJob(this);
+    }
+    isJobComplete(s) {
+        return Transition.isJobComplete(s);
+    }
+    jobWasInterrupted(s) {
+        return Transition.jobWasInterrupted(s);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  7. COMMIT — crash-safe 3-step protocols
+    //     Each protocol runs three atomic transactions:
+    //     save work → spawn children + semaphore → completion tasks.
+    //     GUID ledger digits allow crash-resume at any step.
+    //     → see protocol.ts
+    // ═════════════════════════════════════════════════════════════════
+    /** Leg 2 protocol: save → spawn → complete (duplex activities) */
+    async executeStepProtocol(delta, shouldFinalize) {
+        return Protocol.executeStepProtocol(this, delta, shouldFinalize);
+    }
+    /** Leg 1 protocol: save → spawn → complete (Category B activities) */
+    async executeLeg1StepProtocol(delta) {
+        return Protocol.executeLeg1StepProtocol(this, delta);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  8. DUPLEX RE-ENTRY — handle Leg 2 responses
+    //     Called when a worker/await/hook returns its result.
+    //     Binds the response, maps job data, and runs the protocol.
+    //     → see process.ts
+    // ═════════════════════════════════════════════════════════════════
+    async processEvent(status = stream_1.StreamStatus.SUCCESS, code = 200, type = 'output') {
+        return Process.processEvent(this, status, code, type);
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  OVERRIDABLE — stubs replaced by specific activity types
+    // ═════════════════════════════════════════════════════════════════
+    setLeg(leg) { this.leg = leg; }
+    async registerTimeout() { }
+    getJobStatus() { return null; }
+    authorizeEntry(_state) { return []; }
+    bindSearchData(_options) { }
+    bindMarkerData(_options) { }
+    /** Job metadata paths to persist (Trigger overrides with full JOB set) */
+    bindJobMetadataPaths() {
+        return State.bindJobMetadataPaths();
+    }
+    /** Activity metadata paths to persist (Trigger overrides; leg-aware) */
+    bindActivityMetadataPaths() {
+        return State.bindActivityMetadataPaths(this.leg);
+    }
+    async getTriggerConfig() {
+        return await this.store.getSchema(this.config.trigger, await this.engine.getVID());
+    }
+    // ═════════════════════════════════════════════════════════════════
+    //  ERROR — shared catch handler for subclass process() methods
+    //  Swallows expected concurrency errors (stale job, duplicate
+    //  delivery, generational mismatch) and re-throws the rest.
+    // ═════════════════════════════════════════════════════════════════
+    handleProcessError(error, telemetry, label) {
+        if (error instanceof errors_1.InactiveJobError) {
+            this.logger.error(`${label}-inactive-job-error`, { error });
+            return;
+        }
+        else if (error instanceof errors_1.GenerationalError) {
+            this.logger.info('process-event-generational-job-error', { error });
+            return;
+        }
+        else if (error instanceof errors_1.GetStateError) {
+            this.logger.error(`${label}-get-state-error`, { error });
+            return;
+        }
+        else if (error instanceof errors_1.CollationError) {
+            if (error.fault === 'duplicate') {
+                this.logger.info(`${label}-collation-overage`, {
+                    job_id: this.context.metadata.jid,
+                    guid: this.context.metadata.guid,
+                });
+                return;
+            }
+            this.logger.error(`${label}-collation-error`, { error });
+        }
+        else {
+            this.logger.error(`${label}-process-error`, { error });
+        }
+        telemetry?.setActivityError(error.message);
+        throw error;
+    }
+}
+exports.Activity = Activity;

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

@@ -0,0 +1,12 @@
+import { ActivityType, ActivityMetadata } from '../../../types/activity';
+import { JobState } from '../../../types/job';
+interface MappingContext {
+    config: ActivityType;
+    context: JobState;
+    metadata: ActivityMetadata;
+}
+export declare function mapInputData(instance: MappingContext): void;
+export declare function mapOutputData(instance: MappingContext): void;
+export declare function mapJobData(instance: MappingContext): void;
+export declare function mapStatusThreshold(instance: MappingContext): number;
+export {};

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

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapStatusThreshold = exports.mapJobData = exports.mapOutputData = exports.mapInputData = void 0;
+const utils_1 = require("../../../modules/utils");
+const mapper_1 = require("../../mapper");
+const pipe_1 = require("../../pipe");
+function mapInputData(instance) {
+    if (instance.config.input?.maps) {
+        const mapper = new mapper_1.MapperService((0, utils_1.deepCopy)(instance.config.input.maps), instance.context);
+        instance.context.data = mapper.mapRules();
+    }
+}
+exports.mapInputData = mapInputData;
+function mapOutputData(instance) {
+    if (instance.config.output?.maps) {
+        const mapper = new mapper_1.MapperService((0, utils_1.deepCopy)(instance.config.output.maps), instance.context);
+        const actOutData = mapper.mapRules();
+        const activityId = instance.metadata.aid;
+        const data = { ...instance.context[activityId].output, ...actOutData };
+        instance.context[activityId].output.data = data;
+    }
+}
+exports.mapOutputData = mapOutputData;
+function mapJobData(instance) {
+    if (instance.config.job?.maps) {
+        const mapper = new mapper_1.MapperService((0, utils_1.deepCopy)(instance.config.job.maps), instance.context);
+        const output = mapper.mapRules();
+        if (output) {
+            for (const key in output) {
+                const f1 = key.indexOf('[');
+                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];
+                        if (obj && typeof obj === 'object') {
+                            Object.keys(obj).forEach((newKey) => {
+                                output[newKey] = obj[newKey];
+                            });
+                        }
+                        delete output[key];
+                    }
+                }
+            }
+        }
+        instance.context.data = output;
+    }
+}
+exports.mapJobData = mapJobData;
+function mapStatusThreshold(instance) {
+    if (instance.config.statusThreshold !== undefined) {
+        const threshold = pipe_1.Pipe.resolve(instance.config.statusThreshold, instance.context);
+        if (threshold !== undefined && !isNaN(Number(threshold))) {
+            return threshold;
+        }
+    }
+    return 0;
+}
+exports.mapStatusThreshold = mapStatusThreshold;

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

@@ -0,0 +1,28 @@
+import { EngineService } from '../../engine';
+import { ILogger } from '../../logger';
+import { ActivityData, ActivityLeg, ActivityMetadata, ActivityType } from '../../../types/activity';
+import { JobState } from '../../../types/job';
+import { StreamCode, StreamData, StreamStatus } from '../../../types/stream';
+interface ProcessContext {
+    config: ActivityType;
+    context: JobState;
+    metadata: ActivityMetadata;
+    engine: EngineService;
+    logger: ILogger;
+    status: StreamStatus;
+    code: StreamCode;
+    data: ActivityData;
+    leg: ActivityLeg;
+    adjacencyList: StreamData[];
+    adjacentIndex: number;
+    setLeg(leg: ActivityLeg): void;
+    verifyReentry(): Promise<number>;
+    bindActivityError(data: Record<string, unknown>): void;
+    bindActivityData(type: 'output' | 'hook'): void;
+    bindJobError(data: Record<string, unknown>): void;
+    filterAdjacent(): Promise<StreamData[]>;
+    mapJobData(): void;
+    executeStepProtocol(delta: number, shouldFinalize: boolean): Promise<boolean>;
+}
+export declare function processEvent(instance: ProcessContext, status?: StreamStatus, code?: StreamCode, type?: 'hook' | 'output'): Promise<void>;
+export {};

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

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processEvent = void 0;
+const enums_1 = require("../../../modules/enums");
+const errors_1 = require("../../../modules/errors");
+const collator_1 = require("../../collator");
+const telemetry_1 = require("../../telemetry");
+const stream_1 = require("../../../types/stream");
+async function processEvent(instance, status = stream_1.StreamStatus.SUCCESS, code = 200, type = 'output') {
+    instance.setLeg(2);
+    const jid = instance.context.metadata.jid;
+    if (!jid) {
+        instance.logger.error('activity-process-event-error', {
+            message: 'job id is undefined',
+        });
+        return;
+    }
+    const aid = instance.metadata.aid;
+    instance.status = status;
+    instance.code = code;
+    instance.logger.debug('activity-process-event', {
+        topic: instance.config.subtype,
+        jid,
+        aid,
+        status,
+        code,
+    });
+    let telemetry;
+    try {
+        const collationKey = await instance.verifyReentry();
+        instance.adjacentIndex =
+            collator_1.CollatorService.getDimensionalIndex(collationKey);
+        telemetry = new telemetry_1.TelemetryService(instance.engine.appId, instance.config, instance.metadata, instance.context);
+        telemetry.startActivitySpan(instance.leg);
+        //bind data per status type
+        if (status === stream_1.StreamStatus.ERROR) {
+            instance.bindActivityError(instance.data);
+            instance.adjacencyList = await instance.filterAdjacent();
+            if (!instance.adjacencyList.length) {
+                instance.bindJobError(instance.data);
+            }
+        }
+        else {
+            instance.bindActivityData(type);
+            instance.adjacencyList = await instance.filterAdjacent();
+        }
+        instance.mapJobData();
+        //mark unrecoverable errors as terminal
+        if (status === stream_1.StreamStatus.ERROR && !instance.adjacencyList?.length) {
+            if (!instance.context.data)
+                instance.context.data = {};
+            instance.context.data.done = true;
+            instance.context.data.$error = {
+                message: instance.data?.message || 'unknown error',
+                code: enums_1.HMSH_CODE_DURABLE_MAXED,
+                stack: instance.data?.stack,
+            };
+        }
+        const delta = status === stream_1.StreamStatus.PENDING
+            ? instance.adjacencyList.length
+            : instance.adjacencyList.length - 1;
+        const shouldFinalize = status !== stream_1.StreamStatus.PENDING;
+        await instance.executeStepProtocol(delta, shouldFinalize);
+        telemetry.mapActivityAttributes();
+        telemetry.setActivityAttributes({});
+    }
+    catch (error) {
+        if (error instanceof errors_1.CollationError) {
+            instance.logger.info(`process-event-${error.fault}-error`, { error });
+            return;
+        }
+        else if (error instanceof errors_1.InactiveJobError) {
+            instance.logger.info('process-event-inactive-job-error', { error });
+            return;
+        }
+        else if (error instanceof errors_1.GenerationalError) {
+            instance.logger.info('process-event-generational-job-error', {
+                error,
+            });
+            return;
+        }
+        else if (error instanceof errors_1.GetStateError) {
+            instance.logger.info('process-event-get-job-error', { error });
+            return;
+        }
+        instance.logger.error('activity-process-event-error', {
+            error,
+            message: error.message,
+            stack: error.stack,
+            name: error.name,
+        });
+        telemetry?.setActivityError(error.message);
+        throw error;
+    }
+    finally {
+        telemetry?.endActivitySpan();
+        instance.logger.debug('activity-process-event-end', { jid, aid });
+    }
+}
+exports.processEvent = processEvent;

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

@@ -0,0 +1,39 @@
+import { EngineService } from '../../engine';
+import { ILogger } from '../../logger';
+import { StoreService } from '../../store';
+import { ActivityMetadata, ActivityType } from '../../../types/activity';
+import { ProviderClient, ProviderTransaction, TransactionResultList } from '../../../types/provider';
+import { JobState } from '../../../types/job';
+import { StreamData } from '../../../types/stream';
+interface ProtocolContext {
+    config: ActivityType;
+    context: JobState;
+    metadata: ActivityMetadata;
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    engine: EngineService;
+    logger: ILogger;
+    adjacencyList: StreamData[];
+    adjacentIndex: number;
+    guidLedger: number;
+    mapStatusThreshold(): number;
+    setState(txn?: ProviderTransaction): Promise<string>;
+    shouldEmit(): boolean;
+    shouldPersistJob(): boolean;
+    resolveThresholdHit(results: TransactionResultList): boolean;
+}
+/**
+ * 3-step Leg2 protocol using GUID ledger for crash-safe resume.
+ * Each step bundles durable writes with its concluding digit
+ * update in a single transaction.
+ */
+export declare function executeStepProtocol(instance: ProtocolContext, delta: number, shouldFinalize: boolean): Promise<boolean>;
+/**
+ * 3-step Leg1 protocol for Category B activities
+ * (Leg1-only with children: Hook passthrough, Signal, Interrupt-another).
+ *
+ * Step A: setState + Leg1 completion + step1 marker
+ * Step B: publish children + semaphore + edge capture
+ * Step C: if edge → completion tasks + finalize
+ */
+export declare function executeLeg1StepProtocol(instance: ProtocolContext, delta: number): Promise<boolean>;
+export {};