Idempotency In Operational Jobs

Summary

Operational jobs must be safe to retry. Idempotency is the difference between recoverable automation and duplicate external side effects.

Problem

A job can fail after an external write succeeds but before internal state is updated. Without durable linkage and operation records, a rerun may create a duplicate target record.

Principle

Record source-to-target identity and operation outcomes at the same level of risk as the external side effect.

Platform Shape

Data sync jobs use ops.sync_link and ops.sync_operation through services/data_sync/linkage and related job helpers. The data sync docs describe how QBO and Spectrum jobs use linkage state to skip, block, retry, or audit external writes.

Source Evidence

• docs/domains/data_sync.md
• services/data_sync/linkage
• services/ops/execution_state/jobs

Related Reading

• docs/engineering/reference/ops-diagnostics.md
• docs/engineering/concepts/retry-resume-cancel.md