Class Cycle

Re-executes an ancestor activity in a new dimensional thread, enabling retry loops and iterative patterns without violating the DAG constraint. The cycle activity targets a specific ancestor (typically a Hook with cycle: true) and sends execution back to that point.

Each cycle iteration runs in a fresh dimensional thread — individual activity state is isolated per iteration, while shared job state (job.maps) accumulates across iterations. This pattern enables retries, polling loops, and iterative processing.

YAML Configuration

app:
  id: myapp
  version: '1'
  graphs:
    - subscribes: retry.start
      expire: 300

      activities:
        t1:
          type: trigger

        pivot:
          type: hook
          cycle: true                    # marks this activity as a cycle target
          output:
            maps:
              retryCount: 0

        do_work:
          type: worker
          topic: work.do
          output:
            schema:
              type: object
              properties:
                result: { type: string }

        retry:
          type: cycle
          ancestor: pivot                # re-execute from this activity
          input:
            maps:
              retryCount:                # increment retry counter each cycle
                '@pipe':
                  - ['{pivot.output.data.retryCount}', 1]
                  - ['{@math.add}']

        done:
          type: hook

      transitions:
        t1:
          - to: pivot
        pivot:
          - to: do_work
        do_work:
          - to: retry
            conditions:
              code: 500                  # cycle on error
          - to: done

Key Behaviors

  • The ancestor field must reference an activity with cycle: true.
  • The cycle activity's input.maps override the ancestor's output data for the next iteration, allowing each cycle to pass different values.
  • Dimensional isolation ensures parallel cycle iterations don't collide.

Execution Model

Cycle is a Category A (Leg 1 only) activity:

  • Maps input data, resolves the re-entry dimensional address, and publishes a stream message addressed to the ancestor activity.
  • The ancestor re-enters via its Leg 2 path in the new dimension.

See

CycleActivity for the TypeScript interface

Hierarchy (view full)

Constructors

constructor

Properties

adjacencyList adjacentIndex code config context data engine guidLedger hook leg logger metadata status

Methods

assertGenerationalId authorizeEntry bindActivityData bindActivityError bindActivityMetadata bindActivityMetadataPaths bindActivityState bindDimensionalAddress bindJobError bindJobMetadata bindJobMetadataPaths bindJobState cycleAncestorActivity executeLeg1StepProtocol executeStepProtocol filterAdjacent getJobStatus getState getTriggerConfig initDimensionalAddress initPolicies initSelf isJobComplete jobWasInterrupted mapInputData mapJobData mapOutputData mapStatusThreshold process processEvent registerTimeout resolveAdjacentDad resolveDad resolveStatus resolveThresholdHit setLeg setState setStatus shouldEmit verifyEntry verifyLeg1Entry verifyReentry

Constructors

constructor

Properties

adjacencyList

adjacencyList: StreamData[]

adjacentIndex

adjacentIndex: number = 0

code

code: number = 200

config

config: CycleActivity

context

context: JobState

data

data: ActivityData

engine

engine: EngineService

guidLedger

guidLedger: number = 0

hook

hook: ActivityData

leg

leg: ActivityLeg

logger

logger: ILogger

metadata

metadata: ActivityMetadata

status

status: StreamStatus = StreamStatus.SUCCESS

Methods

assertGenerationalId

  • assertGenerationalId(jobGID, msgGID?): void

  • if the job is created/deleted/created with the same key, the 'gid' ensures no stale messages (such as sleep delays) enter the workstream. Any message with a mismatched gid belongs to a prior job and can safely be ignored/dropped.

    Parameters

    • jobGID: string
    • OptionalmsgGID: string

    Returns void

authorizeEntry

bindActivityData

bindActivityError

bindActivityMetadata

bindActivityMetadataPaths

bindActivityState

bindDimensionalAddress

bindJobError

  • bindJobError(data): void

  • unhandled activity errors (activities that return an ERROR StreamMessage status and have no adjacent children to transition to) are bound to the job

    Parameters

    • data: Record<string, unknown>

    Returns void

bindJobMetadata

bindJobMetadataPaths

bindJobState

cycleAncestorActivity

  • cycleAncestorActivity(transaction): Promise<string>

  • Trigger the target ancestor to execute in a cycle, without violating the constraints of the DAG. Immutable individual activity state will execute in a new dimensional thread while shared job state can change. This pattern allows for retries without violating the DAG.

    Parameters

    Returns Promise<string>

executeLeg1StepProtocol

  • executeLeg1StepProtocol(delta): 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)

    Parameters

    • delta: number

    Returns Promise<boolean>

    true if this transition caused the job to complete

executeStepProtocol

  • executeStepProtocol(delta, shouldFinalize): Promise<boolean>

  • 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.

    Parameters

    • delta: number
    • shouldFinalize: boolean

    Returns Promise<boolean>

    true if this transition caused the job to complete

filterAdjacent

getJobStatus

getState

getTriggerConfig

initDimensionalAddress

initPolicies

initSelf

isJobComplete

jobWasInterrupted

mapInputData

mapJobData

mapOutputData

mapStatusThreshold

process

processEvent

registerTimeout

resolveAdjacentDad

resolveDad

resolveStatus

resolveThresholdHit

setLeg

setState

setStatus

shouldEmit

verifyEntry

verifyLeg1Entry

  • verifyLeg1Entry(): Promise<boolean>

  • 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.

    Returns Promise<boolean>

verifyReentry

  • verifyReentry(): Promise<number>

  • 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.

    Returns Promise<number>

Settings

Member Visibility

On This Page

YAML ConfigurationKey BehaviorsExecution Model
Constructors
Properties
Methods