@hotmeshio/hotmesh 0.7.0 → 0.8.0

package/build/services/activities/signal.js

@@ -20,34 +20,36 @@ class Signal extends activity_1.Activity {
         });
         let telemetry;
         try {
-            await this.verifyEntry();
+            //Category B: entry with step resume
+            await this.verifyLeg1Entry();
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
-            //save state and notarize early completion (signals only run leg1)
-            const transaction = this.store.transact();
             this.adjacencyList = await this.filterAdjacent();
             this.mapOutputData();
             this.mapJobData();
-            await this.setState(transaction);
-            await collator_1.CollatorService.notarizeEarlyCompletion(this, transaction);
-            await this.setStatus(this.adjacencyList.length - 1, transaction);
-            const multiResponse = (await transaction.exec());
-            //todo: this should execute BEFORE the status is decremented
-            if (this.config.subtype === 'all') {
-                await this.hookAll();
-            }
-            else {
-                await this.hookOne();
-            }
-            //transition to adjacent activities
-            const jobStatus = this.resolveStatus(multiResponse);
-            const attrs = { 'app.job.jss': jobStatus };
-            const messageIds = await this.transition(this.adjacencyList, jobStatus);
-            if (messageIds.length) {
-                attrs['app.activity.mids'] = messageIds.join(',');
+            //Step A: Bundle signal hook with Leg1 completion marker.
+            //hookOne is transactional; hookAll is best-effort (complex multi-step).
+            if (!collator_1.CollatorService.isGuidStep1Done(this.guidLedger)) {
+                const txn1 = this.store.transact();
+                if (this.config.subtype === 'all') {
+                    await this.hookAll();
+                }
+                else {
+                    await this.hookOne(txn1);
+                }
+                await this.setState(txn1);
+                if (this.adjacentIndex === 0) {
+                    await collator_1.CollatorService.notarizeLeg1Completion(this, txn1);
+                }
+                await collator_1.CollatorService.notarizeStep1(this, this.context.metadata.guid, txn1);
+                await txn1.exec();
+                //update in-memory guidLedger so executeLeg1StepProtocol skips Step A
+                this.guidLedger += collator_1.CollatorService.WEIGHTS.STEP1_WORK;
             }
+            //Steps B and C: spawn children + semaphore + edge capture
+            await this.executeLeg1StepProtocol(this.adjacencyList.length - 1);
             telemetry.mapActivityAttributes();
-            telemetry.setActivityAttributes(attrs);
+            telemetry.setActivityAttributes({});
             return this.context.metadata.aid;
         }
         catch (error) {
@@ -102,14 +104,15 @@ class Signal extends activity_1.Activity {
         }
     }
     /**
-     * The signal activity will hook one
+     * The signal activity will hook one. Accepts an optional transaction
+     * so the hook publish can be bundled with the Leg1 completion marker.
      */
-    async hookOne() {
+    async hookOne(transaction) {
         const topic = pipe_1.Pipe.resolve(this.config.topic, this.context);
         const signalInputData = this.mapSignalData();
         const status = pipe_1.Pipe.resolve(this.config.status, this.context);
         const code = pipe_1.Pipe.resolve(this.config.code, this.context);
-        return await this.engine.hook(topic, signalInputData, status, code);
+        return await this.engine.hook(topic, signalInputData, status, code, transaction);
     }
     /**
      * The signal activity will hook all paused jobs that share the same job key.

package/build/services/activities/worker.js

@@ -24,11 +24,11 @@ class Worker extends activity_1.Activity {
             telemetry = new telemetry_1.TelemetryService(this.engine.appId, this.config, this.metadata, this.context);
             telemetry.startActivitySpan(this.leg);
             this.mapInputData();
-            //save state and authorize reentry
+            //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 txResponse = (await transaction.exec());

package/build/services/collator/index.d.ts

@@ -6,6 +6,23 @@ import { Activity } from '../activities/activity';
 import { Cycle } from '../activities/cycle';
 declare class CollatorService {
     static targetLength: number;
+    /**
+     * Positional weights for the 15-digit activity/GUID ledger.
+     *
+     * Position:  1     2     3    4      5     6    7      8-15
+     * Weight:   100T  10T   1T   100B   10B   1B   100M   10M..1
+     */
+    static WEIGHTS: {
+        AUTH: number;
+        FINALIZE: number;
+        LEG1_ENTRY: number;
+        LEG1_COMPLETE: number;
+        STEP1_WORK: number;
+        STEP2_SPAWN: number;
+        STEP3_CLEANUP: number;
+        LEG2_ENTRY: number;
+        GUID_SNAPSHOT: number;
+    };
     /**
      * Upon re/entry, verify that the job status is active
      */
@@ -26,12 +43,60 @@ declare class CollatorService {
      * the origin node can be queried for approval/entry.
      */
     static resolveReentryDimension(activity: Cycle): string;
+    /**
+     * Leg1 entry: increment attempt counter (+1T).
+     * NOT bundled with Leg1 work — exists only to mark entry.
+     */
     static notarizeEntry(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
-    static authorizeReentry(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
+    /**
+     * Leg1 completion: increment +100B to mark Leg1 complete.
+     * For cycle=true activities, also pre-seeds the Leg2 entry counter (+1)
+     * so the first real Leg2 gets adjacentIndex=1 (new dimension).
+     * MUST be bundled in the same transaction as Leg1 durable work.
+     */
+    static notarizeLeg1Completion(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
+    /**
+     * Leg1 early exit: marks Leg1 complete for activities that
+     * only run Leg1 and fully close (e.g., Cycle).
+     * Increment +100B (Leg1 completion marker).
+     */
     static notarizeEarlyExit(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
+    /**
+     * Leg1 early completion: marks Leg1 complete for Leg1-only
+     * activities that spawn children (e.g., Signal, Hook passthrough,
+     * Interrupt-another). Increment +100B.
+     */
     static notarizeEarlyCompletion(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
     /**
-     * sets the synthetic inception key (in case of an overage occurs).
+     * Leg2 entry: atomically increments the activity ledger (+1) and
+     * seeds the GUID ledger with the ordinal IF NOT EXISTS.
+     * Returns [activityLedger, guidLedger] after the compound operation.
+     */
+    static notarizeLeg2Entry(activity: Activity, guid: string, transaction?: ProviderTransaction): Promise<[number, number]>;
+    /**
+     * Step 1: Mark Leg2 work done (+10B on GUID ledger only).
+     * MUST be bundled with Leg2 durable work writes.
+     */
+    static notarizeStep1(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
+    /**
+     * Step 2: Mark children spawned (+1B on GUID ledger only).
+     * The job semaphore update and GUID job-closed snapshot are handled
+     * by the compound `setStatusAndCollateGuid` primitive, which MUST
+     * be called in the same transaction.
+     */
+    static notarizeStep2(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
+    /**
+     * Step 3: Mark job completion tasks done (+100M on GUID ledger only).
+     * MUST be bundled with job completion durable writes.
+     */
+    static notarizeStep3(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
+    /**
+     * Finalize: close the activity to new Leg2 GUIDs (+10T).
+     * Only for non-cycle activities after final SUCCESS/ERROR.
+     */
+    static notarizeFinalize(activity: Activity, transaction: ProviderTransaction): Promise<void>;
+    /**
+     * sets the synthetic inception key (in case an overage occurs).
      */
     static notarizeInception(activity: Activity, guid: string, transaction: ProviderTransaction): Promise<void>;
     /**
@@ -39,40 +104,73 @@ declare class CollatorService {
      */
     static isInceptionOverage(activity: Activity, guid: string): Promise<boolean>;
     /**
-     * verifies both the concrete and synthetic keys for the activity; concrete keys
-     * exist in the original model and are effectively the 'real' keys. In reality,
-     * hook activities are atomized during compilation to create a synthetic DAG that
-     * is used to track the status of the graph in a distributed environment. The
-     * synthetic key represents different dimensional realities and is used to
-     * track re-entry overages (it distinguishes between the original and re-entry).
-     * The essential challenge is: is this a re-entry that is purposeful in
-     * order to induce cycles, or is the re-entry due to a failure in the system?
-     */
-    static notarizeReentry(activity: Activity, guid: string, transaction?: ProviderTransaction): Promise<number>;
-    static notarizeContinuation(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
-    static notarizeCompletion(activity: Activity, transaction?: ProviderTransaction): Promise<number>;
+     * Check if Step 1 (work done) is complete on the GUID ledger.
+     * Position 5 (10B digit) > 0.
+     */
+    static isGuidStep1Done(guidLedger: number): boolean;
+    /**
+     * Check if Step 2 (children spawned) is complete on the GUID ledger.
+     * Position 6 (1B digit) > 0.
+     */
+    static isGuidStep2Done(guidLedger: number): boolean;
+    /**
+     * Check if Step 3 (job completion tasks) is complete on the GUID ledger.
+     * Position 7 (100M digit) > 0.
+     */
+    static isGuidStep3Done(guidLedger: number): boolean;
+    /**
+     * Check if this GUID was responsible for closing the job.
+     * Position 4 (100B digit) > 0 (job closed snapshot).
+     */
+    static isGuidJobClosed(guidLedger: number): boolean;
+    /**
+     * Get the attempt count from the GUID ledger (last 8 digits).
+     */
+    static getGuidAttemptCount(guidLedger: number): number;
+    /**
+     * Gets the digit at a 1-indexed position from a 15-digit ledger value.
+     * The value is left-padded to 15 digits before extraction.
+     */
+    static getDigitAtPosition(num: number, position: number): number;
+    /**
+     * @deprecated Use getDigitAtPosition (1-indexed) instead
+     */
     static getDigitAtIndex(num: number, targetDigitIndex: number): number | null;
+    /**
+     * Extracts the dimensional index from the Leg2 entry counter.
+     * Non-cycle activities: first Leg2 → leg2Count=1 → 1-1=0 (same dimension as Leg1).
+     * Cycle activities: first Leg2 → leg2Count=2 (pre-seeded +1) → 2-1=1 (new dimension).
+     */
     static getDimensionalIndex(num: number): number | null;
-    static isDuplicate(num: number, targetDigitIndex: number): boolean;
-    static isInactive(num: number): boolean;
-    static isPrimed(amount: number, leg: ActivityDuplex): boolean;
     /**
-     * During compilation, the graphs are compiled into structures necessary
-     * for distributed processing; these are referred to as 'synthetic DAGs',
-     * because they are not part of the original graph, but are used to track
-     * the status of the graph in a distributed environment. This check ensures
-     * that the 'synthetic key' is not a duplicate. (which is different than
-     * saying the 'key' is not a duplicate)
+     * Verifies the GUID ledger value for step-level resume decisions.
+     * The GUID ledger is seeded with an ordinal position (last 8 digits)
+     * on first entry; step markers drive all resume/reject logic.
+     *
+     * Fully processed: Step 3 done, or Steps 1+2 done without job closure.
+     * Crash recovery: Any incomplete step combination is allowed for resume.
      */
     static verifySyntheticInteger(amount: number): void;
+    /**
+     * Verifies the activity ledger value at entry boundaries.
+     *
+     * Leg1 enter: pos 3 (1T digit) must be > 0 after +1T (proves seed exists).
+     *             pos 4 (100B) must be 0 (Leg1 not yet complete).
+     *             If pos 3 > 1 and pos 4 == 1, it's a stale/replayed message.
+     *
+     * Leg2 enter: pos 4 (100B) must be > 0 (Leg1 complete, reentry authorized).
+     *             pos 2 (10T) must be 0 (not finalized) — cycle activities exempt.
+     */
     static verifyInteger(amount: number, leg: ActivityDuplex, stage: CollationStage): void;
     static getDimensionsById(ancestors: string[], dad: string): Record<string, string>;
     /**
-     * All non-trigger activities are assigned a status seed by their parent
+     * All non-trigger activities are assigned a status seed by their parent.
+     * Seed: 100000000000000 (pos 1 = 1, authorized for entry)
      */
     static getSeed(): string;
     /**
-     * All trigger activities are assigned a status seed in a completed state
+     * All trigger activities are assigned a status seed in a completed state.
+     * Seed: 101100000000001 (authorized, 1 Leg1 entry, Leg1 complete, 1 Leg2 entry)
      */
     static getTriggerSeed(): string;
     /**