Skip to content

Last reviewed: 2026-08-13 Accepted decision: - ../decisions/accepted/0032-qbo-first-controlled-cutover.md - ../decisions/accepted/0035-controlled-conversion-setup-review-pause.md

Company Conversion Run Contract

Canonical aggregate: CompanyConversionRun

Purpose: - coordinate one attempted company transition into BooksPlus; - preserve the exact source, mapping, reconciliation, approval, application, and resulting-record evidence for that attempt; and - reuse existing import, chart, evidence, period, authorization, audit, and posting authorities without creating a parallel ingestion or journal path.

Identity and scope

Applicability:

  • The aggregate applies only to a replacement scenario in which an existing supported source accounting system is being replaced by BooksPlus.
  • A startup scenario has no existing accounting system to replace and must use ordinary company setup without creating a CompanyConversionRun.
  • Chart setup, fiscal periods, permissions, and supported opening balances are shared downstream capabilities. Their use alone does not establish a conversion or require source-system evidence.

Required run fields: - id; - BooksPlus company id; - source system; - source-company identity; - conversion mode and version; - conversion profile key and version; - cutover date; - company currency; - status; - created timestamp and actor; - updated timestamp and actor; and - append-oriented status history.

The initial conversion mode is controlled_cutover version 1.

Rules: - A run is scoped to exactly one BooksPlus company and one explicitly selected source company. - Multiple attempts may exist for a company, but at most one controlled_cutover run may reach applied for that company. - Run identity is immutable and distinct from every source payload, mapping, chart-import batch, Source Document, journal entry, and audit event. - A run may link one or more same-company immutable AccountingImportRun records with explicit payload roles. - Import-run identity and exact file replay remain governed by the Accounting Import Run Contract. - Candidate identity, replay, conflicts, duplicates, and workflow ownership remain governed by the Accounting Import Candidate Contract.

Initial payload roles: - source company and accounting settings; - chart of accounts; - opening trial balance; and - control schedules and supporting evidence.

The initial QBO controlled-cutover parser accepts two distinct binding source profiles with the same conversion-fact and control shape:

  • representative fixture profile qbo-controlled-cutover-fixture version 2; and
  • qualified live profile qbo-controlled-cutover-live version 1.

The live profile may enter a run only through the qualification rules in the QBO Conversion Connector Contract. A raw qbo-live-api-capture manifest is source evidence, not a stageable CompanyConversionRun payload.

Lifecycle

Allowed statuses: - draft; - staged; - mapped; - reconciled; - approved; - applying; - applied; - failed; - abandoned; and - superseded.

Rules: - Status transitions are attributable and append-oriented. - draft contains no accepted source claim. - staged requires all currently declared import-run links to resolve within the company and source-company scope. - mapped requires one explicit versioned mapping selection and visible dispositions for every required unmapped or transformed source fact. - reconciled requires a current successful conversion control result with no unresolved blocker or material difference. - approved binds the exact source links, profile and mapping versions, cutover parameters, control result, dispositions, and actor attribution in one deterministic approval fingerprint. - applying is a durable recovery state entered from approved before any application step begins. - applied requires every expected BooksPlus result identity and succeeded protected-action audit reference. It is terminal and immutable. - A transient or interrupted application remains applying and resumes the same run idempotently. - failed is a terminal attempt with an explicit reason and audit evidence; it must not conceal a retryable interrupted application. - abandoned requires an explicit reason and preserves all prior review state. - superseded requires a same-company replacement run and reason. The replacement link is immutable. - Applied runs cannot be abandoned, failed, or superseded. - A source, profile, mapping, parameter, control, or disposition change after approval requires a new run that supersedes the old run; approved meaning is never silently rewritten.

Mapping and source evidence

The aggregate must preserve: - exact linked import-run ids and payload roles; - source hashes and lineage carried by those runs; - source-company selection evidence; - conversion profile key and version; - mapping-set identity, version, and deterministic fingerprint; - every required mapping decision and disposition reference; - Source Document references for business evidence when applicable; and - unsupported or deferred source facts as visible non-posting evidence.

Provider fields and mapping rules do not define BooksPlus account, workflow, period, posting, correction, or report meaning. Mapping changes create a new version and do not rewrite a prior approved or applied run.

Conversion control result

One current control result belongs to the run before approval. It records, as applicable: - trial-balance debits, credits, and equality; - balance-sheet comparison; - receivable and payable control balances; - inventory control balance and valuation evidence; - bank and credit-card balances; - included outstanding checks, deposits, payments, and transfers; - sales-tax and payroll-liability balances retained as cutover evidence; - retained earnings and prior-period income treatment; - record counts and amounts by supported source type; - unmapped, rejected, duplicate, conflicting, or transformed record counts and amounts; and - conversion adjustments and their approval references.

Every material difference has exactly one explicit disposition: - corrected mapping; - corrected source or staged fact; - documented conversion adjustment; - accepted immaterial difference under an applicable accepted policy; or - failed conversion.

An unresolved blocker, unsupported currency, unexplained material difference, unresolved duplicate or conflict, missing evidence, or stale mapping/control fingerprint prevents reconciled, approved, and applied status.

Application and posting

  • CompanyConversionRun coordinates application; it does not parse provider payloads, own account maintenance, create ledger entries directly, or weaken downstream authorization.
  • Chart changes use the canonical staged chart-import and account-maintenance behavior.
  • A successfully persisted chart application invalidates prior chart_ready evidence and every older dependent account-role review. The run remains applying and returns a blocked, resumable outcome until ordinary Setup has current review evidence for the exact resulting chart and valid required role assignments.
  • Conversion approval and application do not manufacture Setup acknowledgements. Opening-balance application does not bypass Setup prerequisites.
  • Opening balances use OpeningBalanceSetupReviewService or its canonical successor and the protected central PostingService path.
  • Every posting uses the company currency and an eligible financial period.
  • No adapter, mapping, control result, or import candidate may post directly.
  • Application steps persist their stable request identity and resulting BooksPlus record identity before the run can become applied.
  • Replay or resume reuses an existing successful result and never creates a duplicate chart commit, Source Document, opening-balance entry, or accepted candidate link.
  • A partially completed application remains reviewable and recovery-safe; it is not represented as applied.
  • Resuming after Setup review uses the same application, approval fingerprint, and command identity, reuses the persisted chart step, and posts the opening position at most once.
  • After application, corrections use ordinary account maintenance, Source Document supersession, or Accounting Correction behavior rather than mutation or reapplication of the conversion run.

Authorization and audit

Protected actions: - company_conversion_run.stage; - company_conversion_run.mark_mapped; - company_conversion_run.mark_reconciled; - company_conversion_run.approve; - company_conversion_run.apply; - company_conversion_run.fail; - company_conversion_run.abandon; and - company_conversion_run.supersede.

Rules: - Every protected command resolves actor and company before reading or mutating company-scoped conversion state. - Approval and application require distinct authorization decisions and append-only audit events. - Apply authorization does not replace chart_of_accounts.change, source_document.create, or journal_entry.post authorization where those owned actions occur. - Failed and denied attempts emit value-free audit evidence and do not expose another company's conversion metadata. - A Setup-prerequisite pause records value-free failed-result audit evidence for the apply action while leaving the run applying; it does not represent the conversion attempt as terminally failed. - Fail, abandon, and supersede require a reason. - Approval and application require visible confirmation of the exact approval fingerprint and cutover company. - Audit evidence preserves action, company, actor, run target, result, reason when applicable, machine identity when available, and correlation context.

Replay, concurrency, and recovery

  • Commands carry stable request identity where replay can cause mutation.
  • Exact command replay returns the prior accepted result.
  • Reuse of request identity with changed normalized meaning is a conflict.
  • Concurrent attempts serialize within the company conversion boundary.
  • Database constraints enforce at most one applied initial controlled cutover per company.
  • Application recovery resumes the same applying run from its persisted completed-step identities.
  • An applying run whose chart step is complete but whose exact chart or dependent role review is stale returns a blocked recovery result and directs the operator to ordinary Setup before opening-balance application.
  • Recovery must not infer completion from provider state, descriptive text, or amount equality alone.

Persistence and backup

  • The run, status history, import links, mapping selection and decisions, control result, dispositions, approval, application steps, result links, and supersession relationship are one company-owned aggregate.
  • Ordinary application behavior does not delete conversion history.
  • Persistence is transactional at each aggregate transition and preserves company isolation and immutable approved meaning.
  • The persistence migration that introduces this aggregate must update the canonical company backup catalog and schema version in the same slice.
  • Company backup and restore preserve the complete aggregate, causal status history, linked same-company identities, and one-applied-run constraint.
  • Restore validation blocks missing, cross-company, incompatible, or duplicate applied conversion relationships before company replacement.

Explicit exclusions

This contract does not authorize: - full-history or prior-period transaction reconstruction; - operational customer, vendor, item, receivable, payable, banking, payroll, fixed-asset, or perpetual-inventory subledgers; - foreign-currency conversion or posting; - direct adapter posting; - QuickBooks synchronization; - professional workpaper, professional-access, proposed-adjustment, or support- access workflows; or - live OAuth or provider endpoint behavior owned by the separate qbo-conversion-connector.contract.md.

  • ../decisions/accepted/0032-qbo-first-controlled-cutover.md
  • ../decisions/accepted/0035-controlled-conversion-setup-review-pause.md
  • accounting-import-run.contract.md
  • qbo-conversion-connector.contract.md
  • accounting-import-candidate.contract.md
  • chart-import.contract.md
  • journal-entry.contract.md
  • financial-period.contract.md
  • source-document.contract.md
  • security/audit-event-contract.md
  • security/company-backup-snapshot.contract.md