Phase 2.5 follow-up to #640: engine-side OnPlanComplete hook for DO deferred-flush

[intel352]

Phase 2 cascade (#694, v0.54.0) ships v2 dispatch routing that bypasses IaCProvider.Apply for plugins declaring ComputePlanVersion="v2" in CapabilitiesResponse. DigitalOcean plugin (workflow-plugin-digitalocean) has a post-Apply-loop deferred-flush wrapper for database trusted_sources firewall rules (see workflow-plugin-digitalocean/internal/provider.go:243-274 + provider_deferred_test.go) — flagged in PR #120 review by Copilot.

DO plugin cannot declare v2 in Phase 2 cascade without losing the deferred-flush behavior (Database creates with deferred app-ref trusted_sources would never get full firewall rules applied).

Decision (Phase 2 cascade)

DO plugin v1.2.0 (PR #120) opts out of v2 capability declaration: ships pin-bump-only (workflow v0.53.x→v0.54.0 + minEngineVersion 0.54.0 + plugin.json version bump) but keeps CapabilitiesResponse.ComputePlanVersion empty. wfctl continues v1 dispatch (DOProvider.Apply) for DO consumers; deferred-flush continues to work; v2 hooks do NOT fire for DO.

Other 3 IaC plugins (aws/gcp/azure) ship full v2 declaration as planned.

Phase 2.5 scope

1. Add OnPlanComplete func(context.Context) error (or similar finalizer hook) to iac/wfctlhelpers/ApplyPlanHooks struct.
2. Plumb the hook into wfctl-side v2 dispatch after the per-action loop completes (success OR error paths).
3. Plumb the hook to plugin gRPC: add FinalizeApply RPC on IaCProviderRequired service (proto + plumbing on plugin SDK side).
4. DO plugin v1.3.0 (after Phase 2.5 ships in workflow v0.55.0): implement FinalizeApply server-side calling existing FlushDeferredUpdates; flip CapabilitiesResponse.ComputePlanVersion to "v2".
5. Add regression test ensuring deferred-flush fires under v2 dispatch.

Rollback / coexistence

Workflow v0.54.0 continues to support v1 dispatch for plugins that don't declare v2. DO consumers (e.g. BMW) stay on workflow v0.54.0 + DO v1.2.0 (v1-dispatched) until Phase 2.5 lands.

References

• DO PR refactor: replace concrete type assertions with capability interfaces #120 (workflow-plugin-digitalocean)
• workflow PR feat: workflow#640 Phase 2 — v2 hooks-over-gRPC contract (ApplyResult.Actions + ActionStatus + engine populate + decoder) #694 (v0.54.0)
• DO provider.go:243-274 (regression site)
• DO provider_deferred_test.go (regression gate)
• workflow ADR 0040 (Phase 1 + invariants)
• workflow ADR 0024 (no-compat mandate — v1 dispatch continues for non-declaring plugins; no compat shim was the contract for the wire format, not the dispatch routing)

[intel352]

Phase 2.5 SHIPPED 2026-05-17. Cascade artifacts:

• workflow v0.55.0 (PR feat(iac): IaCProviderFinalizer + OnPlanComplete hook (#695 Phase 2.5) #697, squash sha aac519d; GoReleaser run 25985943298; 18 assets; latest)
• workflow-plugin-digitalocean v1.3.0 (PR feat: decompose V1 CRUD routes into pipeline primitives (#86) #123, squash sha d8a203fd; GoReleaser run 25987516580; 5 assets; latest)

DO now declares ComputePlanVersion="v2" + implements pb.IaCProviderFinalizerServer.FinalizeApply → engine OnPlanComplete hook routes via gRPC at end of v2 dispatch loop → DOProvider's deferred-flush wrapper now reachable under v2 routing (mirror of provider.go:295-307).

Live cloud smoke deferred to next BMW deploy per Phase 2 cascade precedent (transcript at workflow-plugin-digitalocean/docs/runtime-validation/2026-05-17-phase2.5-do-finalize-smoke.md). 8 test layers locked Phase 2.5 invariants (engine deferred-closure exit paths, SDK auto-reg, adapter accessor, wfctl closure 6-branch coverage, regression-gate, DO end-to-end FinalizeApply, per-driver attribution, Capabilities v2 declaration).