Spectrum Provider Boundary
Summary
Spectrum is a useful provider-boundary example for external side effects. Creating or updating accounting records outside the platform requires durable identity linkage, explicit operation state, and retry behavior that does not accidentally duplicate records.
Reader Question
How should a platform call an external accounting system when repeated jobs, partial failures, and unknown provider outcomes can otherwise create duplicate or contradictory records?
Boundary Pattern
The integration edge adapts Spectrum-specific API behavior. Data-sync services own the internal operation model: source identity, target identity, payload shape, command status, retry eligibility, and audit evidence. The provider API call is only one transition in that state machine.
The platform should record durable source-to-target linkage before treating a write as safely recoverable. If a create call times out or returns an ambiguous result, the next attempt should consult operation state rather than blindly issuing another create.
Reusable Lessons
- External writes are state transitions, not helper calls.
- Durable source-to-target identity is the basis of idempotency.
- Provider ambiguity should become an operation issue, not a swallowed log.
- Data-sync services should own retry and repair decisions.
- Integration modules should adapt provider behavior inward, not leak it across jobs and UI surfaces.
Source Evidence
integrations/ext_spectrumpipelines/lakehouse/ingest/spectrumservices/data_sync/jobsdocs/domains/data_sync.md