Skip to content

ADR 0035: Controlled Conversion Pauses for Setup Review

Context

A controlled conversion applies an approved chart through canonical chart maintenance and then posts the approved opening position through OpeningBalanceSetupReviewService. The Setup Readiness Contract separately requires material chart changes to invalidate chart_ready and every older dependent account-role review.

Applying both conversion steps without a review boundary would either retain stale Setup evidence or require the opening-balance owner to bypass its prerequisites. Automatically creating Setup acknowledgements from conversion approval would also claim a user reviewed the resulting BooksPlus chart and role assignments when that review did not occur.

Decision

A controlled conversion pauses after its chart application step is durably persisted. The run remains applying while the resulting BooksPlus chart and required launch-role assignments are reviewed through ordinary Setup.

The chart change invalidates the prior chart_ready acknowledgement and every older dependent account_roles_reviewed acknowledgement. Conversion approval does not create or replace either acknowledgement.

When either prerequisite is not current, the apply command returns a blocked, resumable result. This is not a failed conversion and does not discard the approved run, chart result, or completed-step identity. The blocked attempt records value-free audit evidence and exposes Setup review as its recovery action.

After the user reviews the exact resulting chart and valid role assignments, the same application identity, approval fingerprint, and command identity may resume. Resume reuses the durable chart step, posts opening balances once through OpeningBalanceSetupReviewService and central Posting, and completes the run only after all result identities and audit references are durable.

An interrupted or restarted application follows the same rule. It never recommits the chart, manufactures acknowledgements, bypasses Setup readiness, or creates a duplicate opening-balance entry.

Consequences

  • Replacement conversion has an intentional human review point between chart mutation and opening posting.
  • applying may represent either technical interruption or a known Setup prerequisite pause; the returned result and audit evidence distinguish the reason.
  • Setup remains the owner of chart and account-role review evidence.
  • Existing account-role acknowledgements that do not bind the exact chart fingerprint become stale once under this decision and require ordinary re-review; prior evidence remains preserved.
  • Startup setup and its desktop sequence are unchanged.
  • A later user-facing conversion surface must route the blocked result to the same Guided Setup chart and role review paths before offering resume.