Versioning

Long-running workflows can outlive a deploy. Voltro does not run old JavaScript forever; a resumed run executes the current code. Make that explicit by versioning the workflow definition.

import { workflow } from '@voltro/workflow'
import { Schema } from 'effect'

export const ImportCustomers = workflow({
  name: 'customers.import',
  payload: { uploadId: Schema.String },
  success: Schema.Struct({ imported: Schema.Number }),
  idempotencyKey: ({ uploadId }) => uploadId,
  version: 3,
  compatibleWith: [2, 3],
  patches: ['split-validate-and-write'],
})

Voltro stores workflowVersion and workflowPatches on every _voltro_workflow_runs row when the run starts. The local devtools and Voltro Cloud dashboard show the version chip on run rows, so operators can spot old or incompatible runs during a deploy.

#Compatibility

compatibleWith is operator metadata. Use it to document which run versions the current code can still resume safely. If a change cannot resume old payloads or step layout, bump version and leave the old version out of compatibleWith.

#Patch Markers

patches are named change markers. Keep them short and stable:

patches: [
  'split-validate-and-write',
  'rename-export-step',
]

Patch markers are recorded with the run. They make deploy review and dashboard triage concrete: you can answer which branching changes were active when the run started.

#Rules

• Bump version for payload shape changes, step-order changes that affect replay, or changed external side-effect semantics.
• Keep old payload decoders inside the workflow body only while their version remains compatible.
• Prefer additive payload changes with defaults over breaking changes.
• Use the dashboard version chip during deploys to find runs that started on an older contract.