@hotmeshio/hotmesh 0.6.1 → 0.8.0

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.6.1",
+    "version": "0.8.0",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -23,16 +23,15 @@
         "test:await": "NODE_ENV=test jest ./tests/functional/awaiter/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:compile": "NODE_ENV=test jest ./tests/functional/compile/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect": "NODE_ENV=test jest ./tests/unit/services/connector/* --detectOpenHandles --forceExit --verbose",
-        "test:connect:ioredis": "NODE_ENV=test jest ./tests/unit/services/connector/providers/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:postgres": "NODE_ENV=test jest ./tests/unit/services/connector/providers/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:connect:redis": "NODE_ENV=test jest ./tests/unit/services/connector/providers/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:connect:nats": "NODE_ENV=test jest ./tests/unit/services/connector/providers/nats.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow": "NODE_ENV=test jest ./tests/memflow/*/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:postgres": "HMSH_LOGLEVEL=info NODE_ENV=test jest ./tests/memflow/*/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:basic": "HMSH_LOGLEVEL=info NODE_ENV=test jest ./tests/memflow/basic/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:fatal": "NODE_ENV=test jest ./tests/memflow/fatal/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:goodbye": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/goodbye/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:interceptor": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/interceptor/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:interceptor": "NODE_ENV=test HMSH_LOGLEVEL=info jest ./tests/memflow/interceptor/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:entity": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/entity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:agent": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/agent/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=debug NODE_ENV=test jest ./tests/memflow/helloworld/postgres.test.ts --detectOpenHandles --forceExit --verbose",
@@ -42,37 +41,33 @@
         "test:memflow:nested": "NODE_ENV=test jest ./tests/memflow/nested/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:pipeline": "NODE_ENV=test jest ./tests/memflow/pipeline/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:retry": "NODE_ENV=test jest ./tests/memflow/retry/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:retrypolicy": "NODE_ENV=test jest ./tests/memflow/retry-policy/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:sleep": "NODE_ENV=test jest ./tests/memflow/sleep/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:signal": "NODE_ENV=test jest ./tests/memflow/signal/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:unknown": "NODE_ENV=test jest ./tests/memflow/unknown/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:cycle": "NODE_ENV=test jest ./tests/functional/cycle/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:functional": "NODE_ENV=test jest ./tests/functional/* --detectOpenHandles --forceExit --verbose",
+        "test:functional": "NODE_ENV=test jest ./tests/functional/**/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:emit": "NODE_ENV=test jest ./tests/functional/emit/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:pending": "NODE_ENV=test jest ./tests/functional/pending/index.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:hmsh": "NODE_ENV=test jest ./tests/functional/*.test.ts --detectOpenHandles --verbose --forceExit",
-        "test:hook": "NODE_ENV=test jest ./tests/functional/hook/index.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:interrupt": "NODE_ENV=test jest ./tests/functional/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:hmsh": "NODE_ENV=test jest ./tests/functional/postgres.test.ts --detectOpenHandles --verbose --forceExit",
+        "test:hook": "NODE_ENV=test jest ./tests/functional/hook/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:interrupt": "NODE_ENV=test jest ./tests/functional/interrupt/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:parallel": "NODE_ENV=test jest ./tests/functional/parallel/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:pipe": "NODE_ENV=test jest ./tests/unit/services/pipe/index.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:quorum": "NODE_ENV=test jest ./tests/functional/quorum/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:reclaim": "NODE_ENV=test jest ./tests/functional/reclaim/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:redeploy": "NODE_ENV=test jest ./tests/functional/redeploy/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:quorum": "NODE_ENV=test jest ./tests/functional/quorum/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:reclaim": "NODE_ENV=test jest ./tests/functional/reclaim/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:redeploy": "NODE_ENV=test jest ./tests/functional/redeploy/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:reporter": "NODE_ENV=test jest ./tests/unit/services/reporter/index.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:retry": "NODE_ENV=test jest ./tests/functional/retry/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/functional/sequence/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:signal": "NODE_ENV=test jest ./tests/functional/signal/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:reentrant": "NODE_ENV=test jest ./tests/functional/reentrant/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:retry": "NODE_ENV=test jest ./tests/functional/retry/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:retrypolicy": "NODE_ENV=test jest ./tests/functional/retry-policy/*.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:sequence": "NODE_ENV=test HMSH_LOGLEVEL=info jest ./tests/functional/sequence/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:signal": "NODE_ENV=test jest ./tests/functional/signal/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:status": "NODE_ENV=test jest ./tests/functional/status/index.test.ts --detectOpenHandles --forceExit --verbose",
         "test:providers": "NODE_ENV=test jest ./tests/functional/*/providers/*/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:store:ioredis": "NODE_ENV=test jest ./tests/functional/store/providers/redis/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:store:redis": "NODE_ENV=test jest ./tests/functional/store/providers/redis/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:store:postgres": "NODE_ENV=test jest ./tests/functional/store/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:stream:ioredis": "NODE_ENV=test jest ./tests/functional/stream/providers/redis/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:stream:redis": "NODE_ENV=test jest ./tests/functional/stream/providers/redis/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:stream:postgres": "NODE_ENV=test jest ./tests/functional/stream/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:stream:nats": "NODE_ENV=test jest ./tests/functional/stream/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:sub:ioredis": "NODE_ENV=test jest ./tests/functional/sub/providers/redis/ioredis.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:sub:redis": "NODE_ENV=test jest ./tests/functional/sub/providers/redis/redis.test.ts --detectOpenHandles --forceExit --verbose",
         "test:sub:postgres": "NODE_ENV=test jest ./tests/functional/sub/providers/postgres/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:sub:nats": "NODE_ENV=test jest ./tests/functional/sub/providers/nats/nats.test.ts --detectOpenHandles --forceExit --verbose",
         "test:trigger": "NODE_ENV=test jest ./tests/unit/services/activities/trigger.test.ts --detectOpenHandles --forceExit --verbose",
@@ -114,13 +109,11 @@
         "eslint-config-prettier": "^9.1.0",
         "eslint-plugin-import": "^2.29.1",
         "eslint-plugin-prettier": "^5.1.3",
-        "ioredis": "^5.3.2",
         "javascript-obfuscator": "^0.6.2",
         "jest": "^29.5.0",
         "nats": "^2.28.0",
         "openai": "^5.9.0",
         "pg": "^8.10.0",
-        "redis": "^4.6.13",
         "rimraf": "^4.4.1",
         "terser": "^5.37.0",
         "ts-jest": "^29.0.5",
@@ -130,9 +123,7 @@
         "typescript": "^5.0.4"
     },
     "peerDependencies": {
-        "ioredis": "^4.0.0 || ^5.0.0",
         "nats": "^2.0.0",
-        "pg": "^8.0.0",
-        "redis": "^4.0.0"
+        "pg": "^8.0.0"
     }
 }

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

@@ -1,7 +1,6 @@
 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';
@@ -24,6 +23,7 @@ declare class Activity {
     leg: ActivityLeg;
     adjacencyList: StreamData[];
     adjacentIndex: number;
+    guidLedger: number;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     setLeg(leg: ActivityLeg): void;
     /**
@@ -37,15 +37,48 @@ declare class Activity {
      */
     verifyEntry(): Promise<void>;
     /**
-     * Upon entering leg 2 of a duplexed activity
+     * Upon entering leg 2 of a duplexed activity.
+     * Increments both the activity ledger (+1) and GUID ledger (+1).
+     * Stores the GUID ledger value for step-level resume decisions.
      */
     verifyReentry(): Promise<number>;
     processEvent(status?: StreamStatus, code?: StreamCode, type?: 'hook' | 'output'): Promise<void>;
-    processPending(type: 'hook' | 'output'): Promise<TransactionResultList>;
-    processSuccess(type: 'hook' | 'output'): Promise<TransactionResultList>;
-    processError(): Promise<TransactionResultList>;
-    transitionAdjacent(multiResponse: TransactionResultList, telemetry: TelemetryService): Promise<void>;
+    /**
+     * Executes the 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.
+     *
+     * @returns true if this transition caused the job to complete
+     */
+    executeStepProtocol(delta: number, shouldFinalize: boolean): Promise<boolean>;
+    /**
+     * Extracts the thresholdHit value from transaction results.
+     * The setStatusAndCollateGuid result is the last item.
+     */
+    resolveThresholdHit(results: TransactionResultList): boolean;
+    /**
+     * Extracts the job status from the last result of a transaction.
+     * Used by subclass Leg1 process methods for telemetry.
+     */
     resolveStatus(multiResponse: TransactionResultList): number;
+    /**
+     * Leg1 entry verification for Category B activities (Leg1-only with children).
+     * Returns true if this is a resume (Leg1 already completed on a prior attempt).
+     * On resume, loads the GUID ledger for step-level resume decisions.
+     */
+    verifyLeg1Entry(): Promise<boolean>;
+    /**
+     * Executes the 3-step Leg1 protocol for Category B activities
+     * (Leg1-only with children, e.g., Hook passthrough, Signal, Interrupt-another).
+     * Uses the incoming Leg1 message GUID as the GUID ledger key.
+     *
+     * Step A: setState + notarizeLeg1Completion + step1 markers (transaction 1)
+     * Step B: publish children + step2 markers + setStatusAndCollateGuid (transaction 2)
+     * Step C: if edge → runJobCompletionTasks + step3 markers + finalize (transaction 3)
+     *
+     * @returns true if this transition caused the job to complete
+     */
+    executeLeg1StepProtocol(delta: number): Promise<boolean>;
     mapJobData(): void;
     mapInputData(): void;
     mapOutputData(): void;
@@ -94,6 +127,10 @@ declare class Activity {
      * @private
      */
     shouldPersistJob(): boolean;
+    /**
+     * Transition method for Category C (Leg1-only, no children, no semaphore change)
+     * and Category D (Trigger) activities. NOT used by the Leg2 step protocol.
+     */
     transition(adjacencyList: StreamData[], jobStatus: JobStatus): Promise<string[]>;
     /**
      * A job with a vale < -100_000_000 is considered interrupted,

package/build/services/activities/activity.js

@@ -18,6 +18,7 @@ class Activity {
         this.status = stream_1.StreamStatus.SUCCESS;
         this.code = 200;
         this.adjacentIndex = 0;
+        this.guidLedger = 0;
         this.config = config;
         this.data = data;
         this.metadata = metadata;
@@ -56,6 +57,7 @@ class Activity {
         }
         catch (error) {
             await collator_1.CollatorService.notarizeEntry(this);
+            //todo: confirm this check is still needed; the edge event cleanup should handle fully
             if (threshold > 0) {
                 if (this.context.metadata.js === threshold) {
                     //conclude job EXACTLY ONCE
@@ -73,14 +75,19 @@ class Activity {
         await collator_1.CollatorService.notarizeEntry(this);
     }
     /**
-     * Upon entering leg 2 of a duplexed activity
+     * Upon entering leg 2 of a duplexed activity.
+     * Increments both the activity ledger (+1) and GUID ledger (+1).
+     * Stores the GUID ledger value for step-level resume decisions.
      */
     async verifyReentry() {
-        const guid = this.context.metadata.guid;
+        const msgGuid = this.context.metadata.guid;
         this.setLeg(2);
         await this.getState();
+        this.context.metadata.guid = msgGuid;
         collator_1.CollatorService.assertJobActive(this.context.metadata.js, this.context.metadata.jid, this.metadata.aid);
-        return await collator_1.CollatorService.notarizeReentry(this, guid);
+        const [activityLedger, guidLedger] = await collator_1.CollatorService.notarizeLeg2Entry(this, msgGuid);
+        this.guidLedger = guidLedger;
+        return activityLedger;
     }
     //********  DUPLEX RE-ENTRY POINT  ********//
     async processEvent(status = stream_1.StreamStatus.SUCCESS, code = 200, type = 'output') {
@@ -108,17 +115,43 @@ class Activity {
             this.adjacentIndex = collator_1.CollatorService.getDimensionalIndex(collationKey);
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
-            let multiResponse;
-            if (status === stream_1.StreamStatus.PENDING) {
-                multiResponse = await this.processPending(type);
-            }
-            else if (status === stream_1.StreamStatus.SUCCESS) {
-                multiResponse = await this.processSuccess(type);
+            //bind data per status type
+            if (status === stream_1.StreamStatus.ERROR) {
+                this.bindActivityError(this.data);
+                this.adjacencyList = await this.filterAdjacent();
+                if (!this.adjacencyList.length) {
+                    this.bindJobError(this.data);
+                }
             }
             else {
-                multiResponse = await this.processError();
+                this.bindActivityData(type);
+                this.adjacencyList = await this.filterAdjacent();
             }
-            this.transitionAdjacent(multiResponse, telemetry);
+            this.mapJobData();
+            //When an unrecoverable error has no matching transitions
+            //(e.g., code 500 from raw errors after retries exhausted),
+            //mark the job as terminally errored so the step protocol
+            //can force completion via the isErrorTerminal path.
+            if (status === stream_1.StreamStatus.ERROR && !this.adjacencyList?.length) {
+                if (!this.context.data)
+                    this.context.data = {};
+                this.context.data.done = true;
+                this.context.data.$error = {
+                    message: this.data?.message || 'unknown error',
+                    code: enums_1.HMSH_CODE_MEMFLOW_MAXED,
+                    stack: this.data?.stack,
+                };
+            }
+            //determine step parameters
+            const delta = status === stream_1.StreamStatus.PENDING
+                ? this.adjacencyList.length
+                : this.adjacencyList.length - 1;
+            const shouldFinalize = status !== stream_1.StreamStatus.PENDING;
+            //execute 3-step protocol
+            const thresholdHit = await this.executeStepProtocol(delta, shouldFinalize);
+            //telemetry
+            telemetry.mapActivityAttributes();
+            telemetry.setActivityAttributes({});
         }
         catch (error) {
             if (error instanceof errors_1.CollationError) {
@@ -151,50 +184,100 @@ class Activity {
             this.logger.debug('activity-process-event-end', { jid, aid });
         }
     }
-    async processPending(type) {
-        this.bindActivityData(type);
-        this.adjacencyList = await this.filterAdjacent();
-        this.mapJobData();
-        const transaction = this.store.transact();
-        await this.setState(transaction);
-        await collator_1.CollatorService.notarizeContinuation(this, transaction);
-        await this.setStatus(this.adjacencyList.length, transaction);
-        return (await transaction.exec());
-    }
-    async processSuccess(type) {
-        this.bindActivityData(type);
-        this.adjacencyList = await this.filterAdjacent();
-        this.mapJobData();
-        const transaction = this.store.transact();
-        await this.setState(transaction);
-        await collator_1.CollatorService.notarizeCompletion(this, transaction);
-        await this.setStatus(this.adjacencyList.length - 1, transaction);
-        return (await transaction.exec());
-    }
-    async processError() {
-        this.bindActivityError(this.data);
-        this.adjacencyList = await this.filterAdjacent();
-        if (!this.adjacencyList.length) {
-            this.bindJobError(this.data);
-        }
-        this.mapJobData();
-        const transaction = this.store.transact();
-        await this.setState(transaction);
-        await collator_1.CollatorService.notarizeCompletion(this, transaction);
-        await this.setStatus(this.adjacencyList.length - 1, transaction);
-        return (await transaction.exec());
-    }
-    async transitionAdjacent(multiResponse, telemetry) {
-        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(',');
-        }
-        telemetry.setActivityAttributes(attrs);
+    /**
+     * Executes the 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.
+     *
+     * @returns true if this transition caused the job to complete
+     */
+    async executeStepProtocol(delta, shouldFinalize) {
+        const msgGuid = this.context.metadata.guid;
+        const threshold = this.mapStatusThreshold();
+        const { id: appId } = await this.engine.getVID();
+        //Step 1: Save work (skip if GUID 10B already set)
+        if (!collator_1.CollatorService.isGuidStep1Done(this.guidLedger)) {
+            const txn1 = this.store.transact();
+            await this.setState(txn1);
+            await collator_1.CollatorService.notarizeStep1(this, msgGuid, txn1);
+            await txn1.exec();
+        }
+        //Step 2: Spawn children + semaphore + edge capture (skip if GUID 1B already set)
+        let thresholdHit = false;
+        if (!collator_1.CollatorService.isGuidStep2Done(this.guidLedger)) {
+            const txn2 = this.store.transact();
+            //queue step markers first
+            await collator_1.CollatorService.notarizeStep2(this, msgGuid, txn2);
+            //queue child publications
+            for (const child of this.adjacencyList) {
+                await this.engine.router?.publishMessage(null, child, txn2);
+            }
+            //queue semaphore update + edge capture LAST (so result is at end)
+            await this.store.setStatusAndCollateGuid(delta, threshold, this.context.metadata.jid, appId, msgGuid, collator_1.CollatorService.WEIGHTS.GUID_SNAPSHOT, txn2);
+            const results = (await txn2.exec());
+            thresholdHit = this.resolveThresholdHit(results);
+            this.logger.debug('step-protocol-step2-complete', {
+                jid: this.context.metadata.jid,
+                aid: this.metadata.aid,
+                delta,
+                threshold,
+                thresholdHit,
+                lastResult: results[results.length - 1],
+                resultCount: results.length,
+            });
+        }
+        else {
+            //Step 2 already done; check GUID snapshot for edge
+            thresholdHit = collator_1.CollatorService.isGuidJobClosed(this.guidLedger);
+        }
+        //Step 3: Job completion tasks (edge hit OR emit/persist, skip if GUID 100M already set)
+        //When an activity marks the job done with an unrecoverable error
+        //(e.g., stopper after max retries), force completion even when the
+        //semaphore threshold isn't hit (the signaler's +1 contribution
+        //prevents threshold 0 from matching).
+        const isErrorTerminal = !thresholdHit
+            && this.context.data?.done === true
+            && !!this.context.data?.$error;
+        const needsCompletion = thresholdHit || this.shouldEmit() || this.shouldPersistJob() || isErrorTerminal;
+        if (needsCompletion && !collator_1.CollatorService.isGuidStep3Done(this.guidLedger)) {
+            const txn3 = this.store.transact();
+            const options = (thresholdHit || isErrorTerminal) ? {} : { emit: !this.shouldPersistJob() };
+            await this.engine.runJobCompletionTasks(this.context, options, txn3);
+            await collator_1.CollatorService.notarizeStep3(this, msgGuid, txn3);
+            const shouldFinalizeNow = (thresholdHit || isErrorTerminal) ? shouldFinalize : this.shouldPersistJob();
+            if (shouldFinalizeNow) {
+                await collator_1.CollatorService.notarizeFinalize(this, txn3);
+            }
+            await txn3.exec();
+        }
+        else if (needsCompletion) {
+            this.logger.debug('step-protocol-step3-skipped-already-done', {
+                jid: this.context.metadata.jid,
+                aid: this.metadata.aid,
+            });
+        }
+        else {
+            this.logger.debug('step-protocol-no-threshold', {
+                jid: this.context.metadata.jid,
+                aid: this.metadata.aid,
+                thresholdHit,
+            });
+        }
+        return thresholdHit;
+    }
+    /**
+     * Extracts the thresholdHit value from transaction results.
+     * The setStatusAndCollateGuid result is the last item.
+     */
+    resolveThresholdHit(results) {
+        const last = results[results.length - 1];
+        const value = Array.isArray(last) ? last[1] : last;
+        return Number(value) === 1;
     }
+    /**
+     * Extracts the job status from the last result of a transaction.
+     * Used by subclass Leg1 process methods for telemetry.
+     */
     resolveStatus(multiResponse) {
         const activityStatus = multiResponse[multiResponse.length - 1];
         if (Array.isArray(activityStatus)) {
@@ -204,6 +287,127 @@ class Activity {
             return Number(activityStatus);
         }
     }
+    /**
+     * Leg1 entry verification for Category B activities (Leg1-only with children).
+     * Returns true if this is a resume (Leg1 already completed on a prior attempt).
+     * On resume, loads the GUID ledger for step-level resume decisions.
+     */
+    async verifyLeg1Entry() {
+        const msgGuid = this.context.metadata.guid;
+        this.setLeg(1);
+        await this.getState();
+        this.context.metadata.guid = msgGuid;
+        const threshold = this.mapStatusThreshold();
+        try {
+            collator_1.CollatorService.assertJobActive(this.context.metadata.js, this.context.metadata.jid, this.metadata.aid, threshold);
+        }
+        catch (error) {
+            if (error instanceof errors_1.InactiveJobError && threshold > 0) {
+                //Dynamic Activation Control: threshold met, close the job
+                await collator_1.CollatorService.notarizeEntry(this);
+                if (this.context.metadata.js === threshold) {
+                    //conclude job EXACTLY ONCE
+                    const status = await this.setStatus(-threshold);
+                    if (Number(status) === 0) {
+                        await this.engine.runJobCompletionTasks(this.context);
+                    }
+                }
+            }
+            throw error;
+        }
+        try {
+            await collator_1.CollatorService.notarizeEntry(this);
+            return false;
+        }
+        catch (error) {
+            if (error instanceof errors_1.CollationError && error.fault === 'duplicate') {
+                if (this.config.cycle) {
+                    //Cycle re-entry: Leg1 already complete from prior iteration.
+                    //Increment Leg2 counter to derive the new dimensional index,
+                    //so children run in a fresh dimensional plane.
+                    const [activityLedger, guidLedger] = await collator_1.CollatorService.notarizeLeg2Entry(this, msgGuid);
+                    this.adjacentIndex =
+                        collator_1.CollatorService.getDimensionalIndex(activityLedger);
+                    this.guidLedger = guidLedger;
+                    return false;
+                }
+                //100B is set — Leg1 work already committed. Load GUID for step resume.
+                const guidValue = await this.store.collateSynthetic(this.context.metadata.jid, msgGuid, 0);
+                this.guidLedger = guidValue;
+                return true;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Executes the 3-step Leg1 protocol for Category B activities
+     * (Leg1-only with children, e.g., Hook passthrough, Signal, Interrupt-another).
+     * Uses the incoming Leg1 message GUID as the GUID ledger key.
+     *
+     * Step A: setState + notarizeLeg1Completion + step1 markers (transaction 1)
+     * Step B: publish children + step2 markers + setStatusAndCollateGuid (transaction 2)
+     * Step C: if edge → runJobCompletionTasks + step3 markers + finalize (transaction 3)
+     *
+     * @returns true if this transition caused the job to complete
+     */
+    async executeLeg1StepProtocol(delta) {
+        const msgGuid = this.context.metadata.guid;
+        const threshold = this.mapStatusThreshold();
+        const { id: appId } = await this.engine.getVID();
+        //Step A: Save work + Leg1 completion marker
+        if (!collator_1.CollatorService.isGuidStep1Done(this.guidLedger)) {
+            const txn1 = this.store.transact();
+            await this.setState(txn1);
+            if (this.adjacentIndex === 0) {
+                //First entry: mark Leg1 complete. On cycle re-entry
+                //(adjacentIndex > 0), Leg1 is already complete and the
+                //Leg2 counter was already incremented by notarizeLeg2Entry.
+                await collator_1.CollatorService.notarizeLeg1Completion(this, txn1);
+            }
+            await collator_1.CollatorService.notarizeStep1(this, msgGuid, txn1);
+            await txn1.exec();
+        }
+        //Step B: Spawn children + semaphore + edge capture
+        let thresholdHit = false;
+        if (!collator_1.CollatorService.isGuidStep2Done(this.guidLedger)) {
+            const txn2 = this.store.transact();
+            await collator_1.CollatorService.notarizeStep2(this, msgGuid, txn2);
+            for (const child of this.adjacencyList) {
+                await this.engine.router?.publishMessage(null, child, txn2);
+            }
+            await this.store.setStatusAndCollateGuid(delta, threshold, this.context.metadata.jid, appId, msgGuid, collator_1.CollatorService.WEIGHTS.GUID_SNAPSHOT, txn2);
+            const results = (await txn2.exec());
+            thresholdHit = this.resolveThresholdHit(results);
+            this.logger.debug('leg1-step-protocol-stepB-complete', {
+                jid: this.context.metadata.jid,
+                aid: this.metadata.aid,
+                delta,
+                threshold,
+                thresholdHit,
+                lastResult: results[results.length - 1],
+            });
+        }
+        else {
+            thresholdHit = collator_1.CollatorService.isGuidJobClosed(this.guidLedger);
+        }
+        //Step C: Job completion tasks (edge hit OR emit/persist)
+        //When an activity marks the job done with an unrecoverable error
+        //(e.g., stopper after max retries), force completion even when the
+        //semaphore threshold isn't hit.
+        const isErrorTerminal = !thresholdHit
+            && this.context.data?.done === true
+            && !!this.context.data?.$error;
+        const needsCompletion = thresholdHit || this.shouldEmit() || this.shouldPersistJob() || isErrorTerminal;
+        if (needsCompletion && !collator_1.CollatorService.isGuidStep3Done(this.guidLedger)) {
+            const txn3 = this.store.transact();
+            const options = (thresholdHit || isErrorTerminal) ? {} : { emit: !this.shouldPersistJob() };
+            await this.engine.runJobCompletionTasks(this.context, options, txn3);
+            await collator_1.CollatorService.notarizeStep3(this, msgGuid, txn3);
+            await collator_1.CollatorService.notarizeFinalize(this, txn3);
+            await txn3.exec();
+        }
+        return thresholdHit;
+    }
     mapJobData() {
         if (this.config.job?.maps) {
             const mapper = new mapper_1.MapperService((0, utils_1.deepCopy)(this.config.job.maps), this.context);
@@ -517,6 +721,10 @@ class Activity {
         }
         return false;
     }
+    /**
+     * Transition method for Category C (Leg1-only, no children, no semaphore change)
+     * and Category D (Trigger) activities. NOT used by the Leg2 step protocol.
+     */
     async transition(adjacencyList, jobStatus) {
         if (this.jobWasInterrupted(jobStatus)) {
             return;

package/build/services/activities/await.js

@@ -25,11 +25,11 @@ 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
+            //save state and mark Leg1 complete
             const transaction = this.store.transact();
             //todo: await this.registerTimeout();
             const messageId = await this.execActivity(transaction);
-            await collator_1.CollatorService.authorizeReentry(this, transaction);
+            await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
             await this.setState(transaction);
             await this.setStatus(0, transaction);
             const multiResponse = (await transaction.exec());

package/build/services/activities/cycle.js

@@ -38,7 +38,7 @@ class Cycle extends activity_1.Activity {
                 'app.job.jss': jobStatus,
             });
             //exit early (`Cycle` activities only execute Leg 1)
-            await collator_1.CollatorService.notarizeEarlyExit(this, transaction);
+            await collator_1.CollatorService.notarizeLeg1Completion(this, transaction);
             (await transaction.exec());
             return this.context.metadata.aid;
         }

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

@@ -13,6 +13,11 @@ declare class Hook extends Activity {
     config: HookActivity;
     constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
     process(): Promise<string>;
+    /**
+     * Static config check: does this activity have a hook or sleep config?
+     * Used for routing before context is loaded.
+     */
+    isConfiguredAsHook(): boolean;
     /**
      * does this activity use a time-hook or web-hook
      */