Skip to content

Last reviewed: 2026-07-30

Accounting Correction Contract

Canonical objects:

  • AccountingCorrection
  • AccountingCorrectionValidationIssue
  • AccountingCorrectionPreparedJournalEntryPreview

Purpose:

  • correct one posted journal entry through an explicit reversal or adjustment;
  • preserve the target entry, its lines, source evidence, period, attribution, and audit history without mutation;
  • keep correction review state distinct from ledger and report truth; and
  • route every correction ledger effect through central Accounting.

Required correction fields

  • id
  • company id
  • correction kind
  • target posted journal-entry id
  • posting date
  • correction reason
  • correction evidence Source Document id
  • status
  • prepared journal-entry preview
  • created timestamp and actor
  • updated timestamp and actor
  • normalized meaning hash
  • posted correction journal-entry id when posted
  • protected-action audit references

Validation issues preserve:

  • severity: warning or error
  • stable code
  • field or scope when applicable
  • business-language message

Prepared previews preserve:

  • correction id and posting mode
  • target journal-entry id and human-visible number
  • correction posting date and resolved financial-period id
  • correction reason and evidence Source Document id
  • ordered account ids, debit, credit, currency, and descriptions
  • target journal-entry-line id for each reversal line
  • target debit and credit totals
  • normalized candidate debit and credit totals when imported
  • reviewed adjustment control totals when adjustment applies
  • prepared debit and credit totals
  • exact differences among the applicable target, candidate, reviewed, and prepared totals

Machine or file corrections also require:

  • source system
  • source object type
  • external object id
  • external event or version id
  • idempotency key
  • import-run and source-group provenance when applicable
  • accepted-candidate identity when accepted

Allowed correction kinds:

  • reversal
  • adjustment

Allowed statuses:

  • staged
  • held_for_review
  • ready_to_post
  • posted
  • abandoned

Posting modes:

  • routine
  • reversal
  • adjustment

Protected actions:

  • accounting_correction.stage
  • accounting_correction.mark_ready
  • accounting_correction.abandon
  • journal_entry.reverse
  • journal_entry.adjust

Correction model

  • A correction targets exactly one posted journal entry in the same company.
  • The target remains posted and immutable.
  • A reversal fully neutralizes one eligible posted entry.
  • An adjustment posts a new balanced entry that changes or reclassifies the accounting position without claiming to erase or replace the target.
  • A correction is not an ordinary inventory adjustment, standard-cost adjustment, close adjustment, migration entry, or generic manual journal entry merely relabeled as a correction.
  • The correction workflow is a distinct protected Accounting workflow. It does not use a Summary Accounting batch.
  • Correction staging, validation issues, previews, and workflow statuses are review state, not ledger or formal report truth.
  • A posted correction journal entry is ledger truth through the same central Accounting posting boundary used by routine entries.
  • Error issues block ready_to_post; warnings remain visible but do not independently authorize or block readiness.
  • posted and abandoned are terminal correction workflow statuses.
  • A posted correction workflow record and its prepared meaning are not silently changed or abandoned.

Target and chain rules

  • The target journal-entry id, not its number, description, source text, account code, provider journal code, or amount, establishes target identity.
  • A reversal may target a posted routine or adjustment entry.
  • A reversal may not target another reversal.
  • An adjustment may target a posted routine, adjustment, or reversal entry.
  • A correction may not target itself or another company's entry.
  • One target may have at most one posted full reversal.
  • An exact retry of that reversal returns the accepted correction result.
  • A different request to reverse an already reversed target is held as a conflict and cannot create another reversal.
  • More than one adjustment may explain changes to the same target. Each remains a separate posted entry with its own reason, evidence, and direct target.
  • The direct target relationship is preserved for every correction. The root original and complete correction chain are derived by following immutable direct relationships.
  • The original or intermediate target is never updated with a reversed or corrected persisted status. Those labels are derived history.

Reversal preparation

  • Launch reversals are full-entry reversals. Partial reversal is deferred.
  • A prepared reversal contains exactly one line for each target line.
  • Each reversal line identifies the target journal-entry-line id that it reverses.
  • The reversal preserves the target line's immutable account id, currency, and amount while exchanging debit and credit.
  • Target line order supplies stable reversal line order.
  • Target descriptions may be carried forward for explanation, but descriptions never select the account, line mapping, or correction kind.
  • A reversal may use the exact historical target account even when that account is now inactive or retired. The account must still exist, retain the same company-scoped identity, and be the account referenced by the target line.
  • Account replacement mappings, current account codes, names, roles, and provider fields must not redirect a reversal line.
  • Candidate or reviewed control totals must reconcile exactly to both the target totals and the prepared reversal totals with debit and credit exchanged.
  • For reversal, target debit equals candidate and prepared credit; target credit equals candidate and prepared debit. Every difference must be zero.

Adjustment preparation

  • An adjustment supplies an explicit balanced set of lines in company currency.
  • Adjustment lines require current same-company active direct-posting accounts.
  • An adjustment may correct only part of the target's effect or reclassify its effect, but it must not describe itself as a partial reversal.
  • The prepared adjustment must reconcile exactly to its reviewed debit and credit control totals.
  • For imported adjustment, normalized candidate totals, reviewed control totals, and prepared totals must match exactly with zero differences.
  • A zero-value adjustment is held and does not create a journal entry.
  • Equal amounts, provider descriptions, journal codes, account codes, or names do not establish an adjustment target or line disposition.

Reason and evidence

  • Every correction requires a nonblank reason written in accounting or business language.
  • Every correction requires one active same-company Source Document that supports the correction decision.
  • The correction evidence is explicit. It is not inferred from the target entry's original evidence.
  • The target's original Source Document and audit history remain linked and unchanged.
  • Superseded or cross-company Source Documents cannot support a new correction.
  • Source Documents continues to own evidence identity, artifacts, and supersession.

Period policy

  • The correction posting date, not the target entry's posting date, determines the correction's financial period.
  • A correction may target an entry from an earlier open, soft-closed, hard-closed, or reopened period without changing that period or entry.
  • reversal and adjustment posting modes are allowed in open and reopened periods.
  • A soft-closed period may accept a reversal or adjustment only through its dedicated correction posting mode, protected action, reason, evidence, preview, and correction authorization. Routine posting remains blocked.
  • A hard-closed period accepts no new correction entry. Posting into that period requires a separately authorized reopen before correction posting.
  • Planned, missing, ambiguous, or out-of-range periods block correction posting.
  • Posting a correction in a later eligible period does not rewrite the target period and is not the deferred prior-period-adjustment workflow.
  • Close adjustments, prior-period-adjustment presentation, and correction-driven reopen automation remain outside this contract.

Posting and account policy

  • Central Accounting owns reversal and adjustment posting modes.
  • A correction workflow may prepare and review a request but cannot write ledger effects directly.
  • All posted correction entries remain balanced, use the company currency, preserve Money precision, receive a new company-scoped journal entry number, and retain posting attribution.
  • The posting mode and target journal-entry id are persisted on the correction journal entry.
  • A reversal line's target journal-entry-line id is persisted on that reversal line.
  • Routine entries must not carry correction target or reversal-line fields.
  • Adjustment lines use routine account eligibility. Reversal lines use the exact historical-account exception defined above.
  • A correction is posted at most once. Recovery after an interrupted write reuses the durable correction record and any existing posted result rather than creating another journal entry.

Authorization and audit

  • Staging, marking ready, abandoning, reversing, and adjusting are separate permission decisions.
  • Adding these protected actions to a registry or broad development/test bundle does not grant them to a production role.
  • accounting_correction.stage and accounting_correction.mark_ready require ordinary company-scoped authorization and audit.
  • accounting_correction.abandon requires a reason and ordinary company-scoped authorization and audit.
  • journal_entry.reverse and journal_entry.adjust require the correction reason, dedicated company-scoped permission, step-up confirmation, and an append-only audit event.
  • A successful posting audit event targets the corrected journal entry. The correction workflow record links that audit event and the resulting correction journal entry.
  • Denied and failed attempts record the resolved company, actor, action, target, result, reason, machine identity when available, and correlation id.
  • Missing actor, company, target, reason, evidence, permission, or required step-up blocks the action before ledger mutation.
  • This contract does not require a second human approver. Production roles may separate preparation and posting permissions without authorizing from role names alone.

Import and replay

  • A file or machine correction must arrive through the correction_or_reversal route with matching explicit correction or reversal change type.
  • Its complete related-original source identity must resolve to the accepted original event in the same company and source-system scope.
  • The accepted original event must resolve to the same posted journal entry targeted by the correction.
  • Initial machine and file intake targets accepted original events. A machine correction of a prior correction remains held for later contract extension.
  • A resolved import relationship moves the candidate from held_for_correction_workflow into correction preparation; it does not by itself authorize posting.
  • A machine reversal's normalized lines and totals must reconcile exactly to the canonically derived full reversal.
  • A machine adjustment's normalized lines must map explicitly to eligible account identities and reconcile exactly to its reviewed control totals.
  • Exact replay requires the same company, source identity, idempotency key, change type, target, and normalized correction meaning.
  • Conflicting reuse of source identity, idempotency key, change type, target, or normalized meaning is held and cannot overwrite accepted correction history.

The correction meaning-hash schema is accounting-correction-meaning-v1. It is lowercase hexadecimal SHA-256 over a deterministic length-delimited UTF-8 representation of:

  • correction kind;
  • target journal-entry id;
  • correction posting date;
  • company currency;
  • normalized reason;
  • correction evidence Source Document id; and
  • ordered prepared lines with account id, debit, credit, and target line id when reversal applies.

Workflow id, journal entry number, import-run identity, source-group identity, timestamps, actor, display codes, names, descriptions, and provider fields are excluded from normalized correction meaning.

Accepted-event relationships

  • The correction journal-entry target is authoritative even when no accepted source accounting event exists, such as for a manual journal entry.
  • BooksPlus must not manufacture external source-event identity for a manual correction.
  • A durably accepted imported correction uses owning workflow route correction_or_reversal and fact type accounting_correction.
  • Its source-event stage is reversal_accepted for a reversal or adjustment_accepted for an adjustment. Workflow status changes do not rewrite that accepted source-event stage.
  • When an imported correction and its target both have accepted accounting event references, the correction event is the relationship source and the target event is the relationship target.
  • A reversal uses relationship type reverses; an adjustment uses corrects.
  • The relationship must be resolved, same-company, version 1, and consistent with the correction kind and direct journal-entry target before posting.
  • A correction relationship explains and validates the link but never authorizes posting, changes event ownership, or creates another posting result.

History and review

  • Formal reports include the target and every posted correction as distinct ledger entries.
  • A report includes each correction by the correction entry's own posting date. Launch Reporting does not retrospectively rewrite a target period or present a prior-period adjustment.
  • Correction status, net corrected effect, root original, and chain are derived from posted journal entries and their immutable direct relationships.
  • Correction workflow records, previews, held proposals, imports, and audit events support review and drilldown but are not formal report truth.
  • Review and drilldown must show recognizable journal entry numbers, posting dates and periods, correction kind, reason, target and resulting entry, evidence, actor, protected-action result, line effects, and the complete correction chain.
  • Held proposals remain visible with structured issues and create no journal entry, accepted correction relationship, or ledger effect.

Held or blocked conditions include:

  • missing, ambiguous, unposted, self-referential, or cross-company targets;
  • unsupported target kind or an already reversed target;
  • partial, zero, unbalanced, different-currency, or unreconciled inputs;
  • missing, superseded, ambiguous, or cross-company evidence;
  • missing or conflicting source identity, idempotency, or change relationship;
  • inactive or retired adjustment accounts;
  • changed or unresolved historical account identity for reversal;
  • unauthorized or unconfirmed protected actions; and
  • ineligible posting periods.

Explicitly deferred

  • partial reversals;
  • machine or file corrections of prior corrections;
  • foreign-currency corrections or exchange differences;
  • prior-period-adjustment presentation;
  • close adjustments and correction-driven reopen automation;
  • migration entries;
  • automated reclassifications, accruals, or amortization;
  • provider-specific correction behavior; and
  • user-interface implementation.
  • ../accounting/posting-and-reversal.md
  • ../accounting/journal-entries.md
  • ../accounting/financial-periods.md
  • journal-entry.contract.md
  • financial-period.contract.md
  • reporting.contract.md
  • accounting-import-candidate.contract.md
  • source-document.contract.md
  • security/role-permission-contract.md
  • security/audit-event-contract.md
  • ../decisions/accepted/0015-accounting-posting-foundation.md
  • ../decisions/accepted/0020-initial-release-scope-and-financial-workflow-taxonomy.md
  • ../decisions/accepted/0022-reviewable-accounting-file-intake.md
  • ../decisions/accepted/0029-cross-workflow-accounting-event-identity.md