Reversibility

Every completed pipeline execution is reversible within its reversibility window (default: 30 minutes). No manual compensation logic required — define compensation steps in your pipeline and Stellrai runs them automatically on rollback.

reversibility.rollback()

Undo a completed execution. Runs compensation handlers for each step in reverse order.

const result = await hdb.reversibility.rollback(
  executionId: string,
  input: {
    reason:    string;
    metadata?: Record<string, unknown>;
  }
): Promise<RollbackResult>

Example

const result = await hdb.reversibility.rollback('exec_abc123', {
  reason: 'user_request',
});

console.log(result.status);            // 'rolled_back'
console.log(result.checkpointRestored); // true
console.log(result.reversedAt);         // ISO 8601 timestamp

Common reasons

Reason	When to use
user_request	User explicitly cancelled
system_error	Downstream service failure
fraud_detected	Fraud signal triggered reversal
policy_violation	Post-execution policy check failed
duplicate_detected	Idempotency check caught a duplicate

Rollback window

The default rollback window is 30 minutes from completedAt. Attempting a rollback after the window closes returns ROLLBACK_WINDOW_EXPIRED.

To extend or disable the window, configure it in the pipeline definition (contact support for enterprise window options).

---

reversibility.replay()

Re-run an execution from the beginning or from a specific checkpoint. Useful for recovering from transient failures without re-authorizing.

const result = await hdb.reversibility.replay(
  executionId: string,
  input: {
    fromCheckpointId?: string;  // omit to replay from start
    metadata?:         Record<string, unknown>;
  }
): Promise<ReplayResult>

Example

// Replay from the beginning
const replay = await hdb.reversibility.replay('exec_abc123', {});

// Replay from a specific checkpoint (skip already-completed steps)
const checkpoints = await hdb.reversibility.getCheckpoints('exec_abc123');
const lastGood = checkpoints.find(c => c.stepId === 'fraud-check');

const replay = await hdb.reversibility.replay('exec_abc123', {
  fromCheckpointId: lastGood.id,
});

console.log(replay.newExecutionId); // the replay's execution ID

The replay creates a new execution with parentExecutionId pointing to the original. Both executions remain in the audit trail.

---

reversibility.getCheckpoints()

List all checkpoints for an execution.

const checkpoints = await hdb.reversibility.getCheckpoints(executionId: string): Promise<CheckpointSummary[]>

interface CheckpointSummary {
  id:          string;
  executionId: string;
  stepId:      string;
  createdAt:   string;  // ISO 8601
}

---

reversibility.getCheckpoint()

Get a specific checkpoint, including its full state snapshot.

const checkpoint = await hdb.reversibility.getCheckpoint(
  executionId:  string,
  checkpointId: string
): Promise<Checkpoint>

---

reversibility.getRollbackLog()

Get the full rollback history for an execution.

const log = await hdb.reversibility.getRollbackLog(executionId: string): Promise<RollbackLog[]>

---

reversibility.getCircuitBreaker()

Get the current circuit breaker state for a pipeline.

const status = await hdb.reversibility.getCircuitBreaker(pipelineId: string): Promise<CircuitBreakerStatus>

---

reversibility.setCircuitBreaker()

Configure automatic circuit breaking for a pipeline. When the breaker trips, all new executions for that pipeline are rejected until it resets.

const status = await hdb.reversibility.setCircuitBreaker(
  pipelineId: string,
  input: {
    enabled:          boolean;
    failureThreshold: number;   // consecutive failures before tripping
    resetTimeoutMs:   number;   // ms before attempting recovery
  }
): Promise<CircuitBreakerStatus>

Example

// Trip after 3 consecutive failures, reset after 60 seconds
await hdb.reversibility.setCircuitBreaker(pipelineId, {
  enabled:          true,
  failureThreshold: 3,
  resetTimeoutMs:   60_000,
});

---

Rollback vs replay

	Rollback	Replay
What it does	Undoes the execution	Re-runs the execution
When to use	User cancelled, fraud, duplicate	Transient failure, retry needed
Compensation steps	Yes — runs in reverse	No
New execution created	No	Yes (linked to original)
Audit trail	Rollback entry added	New execution + parent link
Requirement	Must be within rollback window	Must have checkpoints