Workflow Checkpoints

A workflow checkpoint is an explicit control point emitted by a supported workflow operation. It lets an authorized operator inspect work that is waiting, then release it to continue or cancel it.

Applies to

Workflow checkpoint controls are a beta Enterprise capability for single-node and distributed-worker deployments. Verify that the selected workflow and installed release expose checkpoint controls.

Caution

A workflow checkpoint is not a universal durable transaction boundary. Resume and cancel behavior depends on the workflow that created the checkpoint, and the control does not automatically rewind external side effects.

Do not confuse checkpoints and cursors

LyftData uses several forms of saved state:

State	Purpose
Workflow checkpoint	Waits for an explicit operator or automation decision
Input cursor or checkpoint	Remembers where a source should continue reading
Runtime artifact	Persists component-specific state or evidence
Trigger invocation	Tracks dispatch and optional response status

Resuming a workflow checkpoint does not reset an input cursor. Clearing a runtime artifact does not cancel a workflow checkpoint. Always identify the state family before taking action.

Checkpoint states

Checkpoint records use these states:

• accepted: waiting for a decision;
• released: resumed by an authorized operator;
• canceled: canceled by an authorized operator;
• expired: the workflow’s deadline passed; and
• rejected: the checkpoint was not accepted for control.

Only an accepted checkpoint can transition through the resume or cancel operation. Repeating the same terminal action does not dispatch a second terminal checkpoint update.

Inspect checkpoints

The checkpoint capability is beta; the installed API routes are classified as stable. List and get use the ui-read scope and currently accept viewer, user, or admin principals within their visible tenant scope. Resume and cancel use ui-write, which is currently admin-only. See API Authentication before scripting these operations.

List visible checkpoints:

curl -fsS \
  -H "Authorization: Bearer ${LYFTDATA_JWT}" \
  "https://<server>:3000/api/checkpoints?state=accepted&limit=100"

Optional filters are tenant_id, environment_id, state, and limit. Multi-tenant administrators should select the intended tenant explicitly.

Fetch one checkpoint before changing it:

curl -fsS \
  -H "Authorization: Bearer ${LYFTDATA_JWT}" \
  "https://<server>:3000/api/checkpoints/<checkpoint-id>"

Review at least the tenant, environment, namespace, job, optional workflow step, creation and expiry times, and current state. The kv_namespace and kv_key identify the workflow-owned coordination state; they are not instructions to edit Worker KV directly.

Resume a checkpoint

Resume only after verifying that downstream systems are ready and that retrying or continuing cannot repeat an unsafe external effect:

curl -fsS -X POST \
  -H "Authorization: Bearer ${LYFTDATA_JWT}" \
  -H "Content-Type: application/json" \
  -d '{"reason":"change approved under CR-142"}' \
  "https://<server>:3000/api/checkpoints/<checkpoint-id>/resume"

The checkpoint becomes released, records the actor and reason, and emits the terminal checkpoint update used by the waiting workflow.

Cancel a checkpoint

Cancel when the waiting operation must not continue:

curl -fsS -X POST \
  -H "Authorization: Bearer ${LYFTDATA_JWT}" \
  -H "Content-Type: application/json" \
  -d '{"reason":"destination maintenance window"}' \
  "https://<server>:3000/api/checkpoints/<checkpoint-id>/cancel"

Cancellation records a canceled result and emits the terminal checkpoint update. How the waiting workflow responds depends on its implementation. The operation does not undo work completed before the checkpoint or compensate external systems. Run the workflow’s documented cleanup or rollback procedure separately.

Safe operating procedure

1. List accepted checkpoints for the exact tenant and environment.
2. Fetch the selected checkpoint again immediately before acting.
3. Confirm the job, workflow step, age, expiry, and external side effects.
4. Choose resume or cancel and provide a meaningful reason.
5. Fetch the record again and confirm its terminal state and recorded actor.
6. Watch Messages, logs, and the target job for the resulting checkpoint update.
7. Capture any required runtime receipt.

If the API cannot publish the terminal update, treat the action as failed and inspect the returned response and server logs. Do not force the checkpoint state through direct database edits.

Design workflows for safe checkpointing

• Place checkpoints before irreversible actions where practical.
• Give the checkpoint a stable namespace and a human-readable operational purpose.
• Define expiry and cancellation behavior.
• Make downstream operations idempotent where the target supports it.
• Record how resume, cancel, timeout, and replay interact with source cursors.
• Capture an external receipt when continuation changes another system.

See Triggers for starting workflow-backed actions and Delivery Semantics for retry, duplication, ordering, and replay boundaries.