Idempotency
Needed when an event or operation repeats. The same intent must not create a second external identity merely because the acknowledgement was lost.
In development / control-plane design
Branchplane
Early design work for an ephemeral environment control plane.
Current state
Branchplane is early design work. There is not enough implementation yet for a source-backed case study, so this page records the problem, intended system model, and open correctness requirements only.
The problem is continuity
“PR opened, run provisioning, done” assumes the process and the world move together. They do not. A provider may create a resource and lose the response. A worker may stop after the third of five resources. An event may arrive twice. Cleanup may succeed everywhere except DNS.
An in-memory workflow forgets what it intended when its process exits. The infrastructure remains. The working premise for Branchplane is that desired environment state must outlive any worker attempting to realize it.
A successful request is not the invariant. Continued convergence is.
The system model
The intended model starts when a branch event changes desired state. Durable control-plane state would record that intent and stable resource identities. A reconciler would observe external state, calculate the difference, ask resource adapters to make bounded changes, record what happened, and return later.
- 01Branch eventChanges intent
- 02Desired statePersists beyond a worker
- 03ReconcileObserve, compare, act
- 04Resource adaptersApply bounded changes
AppDatabaseBrokerDNSObserve
Observed state returns to reconciliationProvider results and drift inform the next safe attempt.
- Desired state
- What should exist for this environment now.
- Actual state
- What providers report as existing now.
- Resource identity
- The stable key that connects control-plane records to external objects.
- Adapter
- A provider-specific boundary for observing and applying one resource type.
Reconciliation
The design uses reconciliation to turn a one-shot sequence into repeated, inspectable attempts. Each attempt would need to be safe to resume, safe to retry where the external operation permits it, and small enough to explain after a crash.
01Observe→02Compare→03Plan→04Act→05Persist→06Repeat
Convergence is eventual. The system can be between states while an operation runs or a retry waits. The design obligation is to make that intermediate state explicit and ensure the next valid worker can continue from durable facts.
Correctness under failure
Leases and fencing
A lease can bound temporary ownership. A monotonically increasing fencing token is still required to reject a stale worker that resumes after ownership has moved.
Retry and backoff
Only transient failures should retry automatically. Permanent configuration or permission failures need durable visibility, not an infinite hot loop.
Deletion
Absence is a desired state. Cleanup must be reconciled resource by resource because partial deletion is as real as partial creation.
Failure scenarios
Worker stops mid-provisionDurable progress lets another valid worker observe and continue.
Create succeeds, response is lostStable identity and provider observation prevent blind duplication.
Two reconcilers overlapLease ownership plus fencing must reject stale writes.
One delete operation failsDesired state remains deleted; later attempts continue toward absence.
External state driftsObservation exposes the difference and schedules corrective work.
Observability and tradeoffs
The useful unit of observation is the reconciliation attempt: what environment ran, which desired generation it saw, what resource changed, why it retried, and whether it moved the system closer to convergence. The available evidence does not establish specific metrics or traces, so none are presented as implemented.
What this architecture buys
Crash recovery, explicit intent, and a place to reason about drift.
What it costs
Eventual consistency, coordination state, provider-specific edge cases, and more machinery than a linear deployment job.