@hotmeshio/hotmesh 0.7.0 → 0.9.0

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

@@ -1,20 +1,75 @@
 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';
 /**
- * The base class for all activities
+ * Base class for all HotMesh activity types. Activities are the execution
+ * units within a YAML-defined workflow graph. Each activity represents a
+ * node in a Directed Acyclic Graph (DAG) that the engine orchestrates.
+ *
+ * ## Activity Categories
+ *
+ * Activities fall into three execution categories:
+ *
+ * - **Category A (Duplex)**: Two-phase activities with Leg 1 (dispatch) and
+ *   Leg 2 (response). Used by `Worker` and `Await`. Leg 1
+ *   publishes a message and waits; Leg 2 handles the response via
+ *   `processEvent` and transitions to adjacent activities.
+ *
+ * - **Category B (Leg1-only with children)**: Single-phase activities that
+ *   execute work and transition to children using the crash-safe
+ *   `executeLeg1StepProtocol`. Used by `Hook` (passthrough mode),
+ *   `Signal`, and `Interrupt` (target mode).
+ *
+ * - **Category C (Leg1-only, no children)**: Terminal activities that
+ *   execute without spawning children. Used by `Interrupt` (self mode).
+ *
+ * ## Shared YAML Configuration
+ *
+ * All activity types support these base properties in the YAML descriptor:
+ *
+ * | Property             | Type    | Description |
+ * |----------------------|---------|-------------|
+ * | `type`               | string  | Activity type: `trigger`, `worker`, `await`, `hook`, `signal`, `interrupt`, `cycle` |
+ * | `title`              | string  | Human-readable label for the activity |
+ * | `input.schema`       | object  | JSON Schema for input validation |
+ * | `input.maps`         | object  | Maps data from other activities into this activity's input |
+ * | `output.schema`      | object  | JSON Schema for output validation |
+ * | `output.maps`        | object  | Maps/transforms the activity's own output data |
+ * | `job.maps`           | object  | Maps activity data to the shared job state |
+ * | `emit`               | boolean | If `true`, emits a message to the graph's `publishes` topic |
+ * | `persist`            | boolean | If `true`, emits the job-completed event while keeping the job active |
+ * | `expire`             | number  | Seconds until the job expires after completion (`-1` = forever) |
+ * | `statusThreshold`    | number  | Custom semaphore threshold for Dynamic Activation Control |
+ * | `cycle`              | boolean | If `true`, leaves Leg 2 open so the activity can be re-entered |
+ *
+ * ## Data Mapping Syntax
+ *
+ * Mapping expressions use curly-brace references to bind data between
+ * activities and the shared job state:
+ *
+ * ```yaml
+ * input:
+ *   maps:
+ *     x: '{t1.output.data.fieldName}'      # reference another activity's output
+ *     y: '{$self.output.data.fieldName}'    # reference own output
+ *     z: '{$job.data.fieldName}'            # reference shared job state
+ *     s: '{$app.settings.configKey}'        # reference app-level settings
+ * ```
+ *
+ * @see {@link https://hotmeshio.github.io/sdk-typescript/docs/quickstart | Quick Start Guide}
+ * @see [Model Driven Development](https://hotmeshio.github.io/sdk-typescript/docs/model_driven_development)
  */
 declare class Activity {
     config: ActivityType;
     data: ActivityData;
     hook: ActivityData;
     metadata: ActivityMetadata;
+    /** @hidden */
     store: StoreService<ProviderClient, ProviderTransaction>;
     context: JobState;
     engine: EngineService;
@@ -24,6 +79,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 +93,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;
@@ -62,7 +151,7 @@ declare class Activity {
     getTriggerConfig(): Promise<ActivityType>;
     getJobStatus(): null | number;
     setStatus(amount: number, transaction?: ProviderTransaction): Promise<void | any>;
-    authorizeEntry(state: StringAnyType): string[];
+    authorizeEntry(_state: StringAnyType): string[];
     bindDimensionalAddress(state: StringAnyType): void;
     setState(transaction?: ProviderTransaction): Promise<string>;
     bindJobMetadata(): void;
@@ -94,7 +183,6 @@ declare class Activity {
      * @private
      */
     shouldPersistJob(): boolean;
-    transition(adjacencyList: StreamData[], jobStatus: JobStatus): Promise<string[]>;
     /**
      * A job with a vale < -100_000_000 is considered interrupted,
      * as the interruption event decrements the job status by 1billion.

package/build/services/activities/activity.js

@@ -11,13 +11,69 @@ const serializer_1 = require("../serializer");
 const telemetry_1 = require("../telemetry");
 const stream_1 = require("../../types/stream");
 /**
- * The base class for all activities
+ * Base class for all HotMesh activity types. Activities are the execution
+ * units within a YAML-defined workflow graph. Each activity represents a
+ * node in a Directed Acyclic Graph (DAG) that the engine orchestrates.
+ *
+ * ## Activity Categories
+ *
+ * Activities fall into three execution categories:
+ *
+ * - **Category A (Duplex)**: Two-phase activities with Leg 1 (dispatch) and
+ *   Leg 2 (response). Used by `Worker` and `Await`. Leg 1
+ *   publishes a message and waits; Leg 2 handles the response via
+ *   `processEvent` and transitions to adjacent activities.
+ *
+ * - **Category B (Leg1-only with children)**: Single-phase activities that
+ *   execute work and transition to children using the crash-safe
+ *   `executeLeg1StepProtocol`. Used by `Hook` (passthrough mode),
+ *   `Signal`, and `Interrupt` (target mode).
+ *
+ * - **Category C (Leg1-only, no children)**: Terminal activities that
+ *   execute without spawning children. Used by `Interrupt` (self mode).
+ *
+ * ## Shared YAML Configuration
+ *
+ * All activity types support these base properties in the YAML descriptor:
+ *
+ * | Property             | Type    | Description |
+ * |----------------------|---------|-------------|
+ * | `type`               | string  | Activity type: `trigger`, `worker`, `await`, `hook`, `signal`, `interrupt`, `cycle` |
+ * | `title`              | string  | Human-readable label for the activity |
+ * | `input.schema`       | object  | JSON Schema for input validation |
+ * | `input.maps`         | object  | Maps data from other activities into this activity's input |
+ * | `output.schema`      | object  | JSON Schema for output validation |
+ * | `output.maps`        | object  | Maps/transforms the activity's own output data |
+ * | `job.maps`           | object  | Maps activity data to the shared job state |
+ * | `emit`               | boolean | If `true`, emits a message to the graph's `publishes` topic |
+ * | `persist`            | boolean | If `true`, emits the job-completed event while keeping the job active |
+ * | `expire`             | number  | Seconds until the job expires after completion (`-1` = forever) |
+ * | `statusThreshold`    | number  | Custom semaphore threshold for Dynamic Activation Control |
+ * | `cycle`              | boolean | If `true`, leaves Leg 2 open so the activity can be re-entered |
+ *
+ * ## Data Mapping Syntax
+ *
+ * Mapping expressions use curly-brace references to bind data between
+ * activities and the shared job state:
+ *
+ * ```yaml
+ * input:
+ *   maps:
+ *     x: '{t1.output.data.fieldName}'      # reference another activity's output
+ *     y: '{$self.output.data.fieldName}'    # reference own output
+ *     z: '{$job.data.fieldName}'            # reference shared job state
+ *     s: '{$app.settings.configKey}'        # reference app-level settings
+ * ```
+ *
+ * @see {@link https://hotmeshio.github.io/sdk-typescript/docs/quickstart | Quick Start Guide}
+ * @see [Model Driven Development](https://hotmeshio.github.io/sdk-typescript/docs/model_driven_development)
  */
 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;
@@ -57,11 +113,14 @@ class Activity {
         catch (error) {
             await collator_1.CollatorService.notarizeEntry(this);
             if (threshold > 0) {
-                if (this.context.metadata.js === threshold) {
-                    //conclude job EXACTLY ONCE
+                if (this.context.metadata.js <= threshold) {
+                    //Dynamic Activation Control: convergent claim — only the
+                    //activity whose HINCRBY reaches exactly 0 runs completion.
                     const status = await this.setStatus(-threshold);
                     if (Number(status) === 0) {
-                        await this.engine.runJobCompletionTasks(this.context);
+                        const txn = this.store.transact();
+                        await this.engine.runJobCompletionTasks(this.context, {}, txn);
+                        await txn.exec();
                     }
                 }
             }
@@ -73,14 +132,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 +172,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 +241,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 +344,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);
@@ -282,13 +543,10 @@ class Activity {
         const { id: appId } = await this.engine.getVID();
         return await this.store.setStatus(amount, this.context.metadata.jid, appId, transaction);
     }
-    authorizeEntry(state) {
-        //pre-authorize activity state to allow entry for adjacent activities
-        return (this.adjacencyList?.map((streamData) => {
-            const { metadata: { aid }, } = streamData;
-            state[`${aid}/output/metadata/as`] = collator_1.CollatorService.getSeed();
-            return aid;
-        }) ?? []);
+    authorizeEntry(_state) {
+        //seed writes removed: child activities increment from 0 (null field).
+        //FINALIZE (200T) sets pos 1 directly to 2 without needing a 100T base.
+        return [];
     }
     bindDimensionalAddress(state) {
         const dad = this.resolveDad();
@@ -517,27 +775,6 @@ class Activity {
         }
         return false;
     }
-    async transition(adjacencyList, jobStatus) {
-        if (this.jobWasInterrupted(jobStatus)) {
-            return;
-        }
-        let mIds = [];
-        if (this.shouldEmit() ||
-            this.isJobComplete(jobStatus) ||
-            this.shouldPersistJob()) {
-            await this.engine.runJobCompletionTasks(this.context, {
-                emit: !this.isJobComplete(jobStatus) && !this.shouldPersistJob(),
-            });
-        }
-        if (adjacencyList.length && !this.isJobComplete(jobStatus)) {
-            const transaction = this.store.transact();
-            for (const execSignal of adjacencyList) {
-                await this.engine.router?.publishMessage(null, execSignal, transaction);
-            }
-            mIds = (await transaction.exec());
-        }
-        return mIds;
-    }
     /**
      * A job with a vale < -100_000_000 is considered interrupted,
      * as the interruption event decrements the job status by 1billion.