Last reviewed: 2026-08-02

Starter Chart Installation Contract

Canonical workflow: StarterChartInstallation

Required concepts

company and actor context
chart key and durable chart version
preflight result
existing-code collision snapshot
explicit resolution decision
installation or reviewed-chart result
account history and audit evidence
correlation and replay identity

Preflight

Installation must preflight the complete selected chart before mutation.
Preflight resolves an already-installed row by company and immutable standard_account_key, not by its current code or name.
An exact company-scoped code match without the expected standard account key is a collision. Code, name, number range, source, and prior implementation behavior do not establish compatibility.
Every collision must be presented together before installation continues.
A pending collision review is durable and makes chart readiness blocked.

Compatibility

A colliding account is compatible for reviewed adoption only when:

it belongs to the installation company;
it has no different standard_account_key;
it is active, posting, and allows direct posting;
its explicit account type, normal balance, control-account flag, and contra status match the selected starter-chart row; and
assigning the row's singleton or required-singleton roles would not silently replace another account.

Name, source, account-number range, and prior activity neither prove nor prevent compatibility. An incompatible account must not be changed merely to make adoption pass.

Reviewed resolutions

Compatible adoption requires an explicit protected decision for every collision in the pending review.
Adoption preserves account id, source, code, name, effective history, prior activity, and audit history. It assigns the immutable standard_account_key, records the selected chart version and reviewed property snapshot, and then applies canonical role assignments.
Incompatible collisions cannot be adopted.
The user may cancel without account or role mutation, use authorized account maintenance and retry, or explicitly retain the existing chart as the reviewed-chart alternative.
Retaining the existing chart does not assign starter-chart identity or roles. Required launch roles must be assigned and reviewed separately.
Silent renumbering, deletion, database reset, source rewriting, and silent singleton-role replacement are prohibited resolutions.

Recovery, replay, and readiness

A resolution verifies the exact company, chart key and version, account id, account version, and reviewed semantic properties before mutation.
Exact replay is idempotent. A changed account or changed chart meaning is a visible conflict requiring a new review.
Applied work must be recoverable after interruption without duplicating accounts, roles, standard identity, history, or audit meaning.
Pending or changed-meaning collision review blocks chart readiness even when an older chart acknowledgement exists.
After adoption or acceptance of the reviewed-chart alternative, chart and account-role acknowledgements older than that resolution are stale.
Account-role readiness remains blocked until required roles resolve to eligible same-company accounts without forbidden duplication.

Security and audit

Starting, accepting, or cancelling collision review and adopting an account are protected accounting-configuration actions.
Successful and denied consequential actions remain attributable and explainable through append-only audit evidence.
Adoption history identifies the account, standard account key, chart version, actor, reason, time, and correlation reference without rewriting prior provenance.

account.contract.md
account-role.contract.md
chart-import.contract.md
../accounting/accounts.md
../decisions/accepted/0017-chart-maintenance-surrounds-accounting-kernel.md
../decisions/accepted/0023-booksplus-starter-chart-and-dolibarr-account-crosswalk.md