Skip to content

Source truth: - Company Identity and Context Contract - Account Contract - Starter Chart Installation Contract - Dolibarr Account Crosswalk Contract - Journal Entry Contract - Accounting Correction Contract - Close Run Contract - Reporting Contract - Money Contract - Accounting Posting Foundation ADR - Financial Period Contract - Purchasing and Payables Summary Fact Contract - Banking and Finance Summary Fact Contract - Sales Tax Accounting and Remittance Contract - Actor Identity Contract - Roles and Permissions Contract - Protected Actions Contract - Security Audit Event Contract - Backup Security Contract - Company Backup Snapshot Contract

Implementation Contracts

Implementation work should follow the canonical contracts defined in the truth section.

  • Account contract
  • Account role contract
  • Account code resolution contract
  • Chart import contract
  • Starter chart installation contract
  • Dolibarr account crosswalk contract
  • Company identity and context contract
  • Setup readiness contract
  • Financial period contract
  • Journal entry contract
  • Accounting correction contract
  • Close run contract
  • Reporting contract
  • Summary accounting batch contract
  • Purchasing and Payables Summary fact contract
  • Banking and Finance Summary fact contract
  • Sales Tax Accounting and Remittance contract
  • Source document contract
  • Money contract
  • Actor identity contract
  • Roles and permissions contract
  • Protected actions contract
  • Security audit event contract
  • Backup security contract
  • Company backup snapshot contract

Security implementation slice

The developer test identity slice should implement security behavior as ordinary domain and application behavior:

  • place actor, role, permission, protected-action, and policy logic under BooksPlus.Domain.Security;
  • place append-only audit event contracts under BooksPlus.Domain.Audit;
  • pass actor, company, protected action, target, and correlation context through application services according to the company contract;
  • use the persisted company model for BooksPlus Test Company; do not rely on an implicit default company for protected work;
  • seed BooksPlus Test Company, Developer Test User, and Developer Test Full Access only in explicit development/test mode;
  • generate the development/test full-access bundle from the protected action registry;
  • reject protected commands that cannot resolve required actor and company context before domain mutation;
  • record the resolved company identifier on company-scoped audit events.

Accounting posting foundation slice

The first accounting posting foundation should implement the accepted posting ADR as ordinary accounting domain and application behavior:

  • place account, journal-entry, money, and posting policy behavior under the accounting/shared domain areas named by the architecture guidance;
  • expose one central posting service for routine posting rather than allowing screens, imports, close, or feature-specific components to persist ledger effects directly;
  • enforce active-account, balanced-entry, same-currency, source-reference, explanation, attribution, and financial-period eligibility rules before persistence;
  • treat entries created in this slice as posted-only records;
  • assign a company-scoped human-visible journal entry number inside the central posting path before persistence;
  • keep journal entry numbers immutable and unique within company while preserving ids as durable internal identity;
  • use journal_entry.post as the protected action name for routine posting;
  • emit an attributable audit event for successful and rejected consequential posting attempts according to the security audit contract;
  • keep draft journal entries, close adjustments, and automated-posting idempotency outside the initial posting foundation; implement reversals and adjustments only through the later Accounting Correction Contract and its dedicated slices.

Summary accounting foundation slice

The summary accounting foundation should implement summary intake as reviewable workflow state before ledger posting:

  • assign a company-scoped human-visible summary batch number inside the central intake path before persistence;
  • reserve a new summary batch number only when creating a new batch, not when returning an idempotent replay;
  • keep summary batch numbers immutable and unique within company while preserving ids as durable internal identity;
  • format summary batch references as SA- followed by at least six digits in user-facing registers, exception messages, and drilldown labels;
  • keep assigned summary batch numbers out of normalized meaning hashes, source identity comparisons, and source-system semantics;
  • continue using central Accounting posting for ledger effects from ready summary batches.

Accounting correction slices

Correction implementation must follow the Accounting Correction Contract:

  • keep correction preparation, issues, preview, readiness, and abandonment in a distinct Accounting workflow rather than Summary Accounting;
  • derive full reversal lines from immutable target journal-entry lines and preserve their target-line ids;
  • require active same-company correction evidence, a nonblank reason, and an exact same-company posted target before readiness;
  • use current active direct-posting accounts for adjustments and exact historical target account ids for full reversals;
  • persist posting mode and direct correction target on the resulting journal entry without mutating the target;
  • apply dedicated staging, readiness, abandonment, reversal, and adjustment protected actions with their required reason, step-up, and audit behavior;
  • allow correction posting in open and reopened periods, allow only protected correction modes in soft-closed periods, and block hard-closed periods until separately reopened;
  • preserve import identity, idempotency, accepted-candidate ownership, and accepted-event relationships where machine or file intake applies, using the canonical accounting_correction fact type and correction-kind stage; and
  • derive correction registers and drilldown from posted ledger relationships while keeping workflow support state out of formal report truth.

Period Close slices

Close implementation must follow the Close Run Contract:

  • keep evaluation snapshots, waivers, approvals, packs, finalization, and reopen under the Close domain rather than generic setup or period-edit UI;
  • preserve one immutable company-scoped run identity, number, target period, mode, policy version, check set, and evaluation fingerprint;
  • evaluate the launch check catalog from repository truth and keep original failed outcomes visible after an allowed waiver;
  • require the latest fresh eligible run for finalization and invalidate stale approvals rather than refreshing snapshots in place;
  • keep hard-close approval distinct from hard-close finalization;
  • link finalization and reopen atomically to append-oriented financial-period state changes and protected audit evidence;
  • keep Close from writing ledger entries, executing reports, or storing evidence artifacts owned by Accounting, Reporting, or Source Documents;
  • enforce exact replay, expected-prior-state concurrency, interruption recovery, and company isolation; and
  • treat existing direct period-transition screens and services as implementation evidence that must be routed behind Close, not as product authority.

Reporting slices

Reporting implementation must follow the Reporting Contract:

  • keep formal amounts derived only from same-company posted journal-entry lines and immutable account identity;
  • implement trial_balance, balance_sheet, and income_statement with the accepted date parameters, account-type formulas, company currency, negative balance visibility, and cumulative unclosed-earnings rule;
  • include reversals and adjustments by their own posting dates without rewriting historical targets;
  • preserve exact accounting precision and block capture of unavailable, unsupported-currency, malformed, cross-company, or out-of-equation results;
  • distinguish live results from immutable company-scoped RR- ReportRuns;
  • persist definition/version, normalized parameters, fingerprints, captured labels, lines, totals, source contributions, attribution, and audit evidence atomically;
  • enforce report.view and report_run.capture, exact replay, concurrency, interruption recovery, company backup, and restore;
  • expose currentness through Reporting without mutating historical snapshots; and
  • let Close consume only the exact Reporting-owned resolver contract rather than executing or reconstructing reports.

Sales-tax accounting and remittance slices

Implementation must follow the Sales Tax Accounting and Remittance Contract:

  • add provider-agnostic capability profiles and tax-result components before changing Sales preparation;
  • keep seller-owned and facilitator-remitted amounts mutually exclusive and reconcile both source-control equations exactly;
  • implement return control and reconciliation persistence independently from the existing Summary batch aggregate and formal Reporting;
  • route remittance ledger effects through central Accounting only after protected approval and recorded external-payment evidence;
  • add the bounded Finance-owned bank match as non-posting support rather than a direct Finance disbursement;
  • integrate the exact versioned Close checks without allowing Close to create tax, return, payment, or ledger meaning;
  • add every protected action, audit target, replay/concurrency boundary, and company-backup catalog change in its owning implementation slice; and
  • expose desktop review only after service, persistence, PostgreSQL, backup, and cross-workflow tests pass.

Chart of accounts slice

The chart of accounts implementation should keep account maintenance around the accounting kernel:

  • preserve immutable account ids on journal lines;
  • treat codes as strings and preserve leading zeros;
  • never infer accounting behavior from account-number patterns;
  • resolve account entry by exact code before optional chart-level shorthand padding;
  • reject inactive, retired, non-posting, wrong-company, and ambiguous accounts with structured results;
  • install starter chart definitions idempotently;
  • enforce semantic-role cardinality through explicit role assignments;
  • record material account changes in account history and protected audit events;
  • stage chart imports for review and validation before committing accounts.

Dolibarr account crosswalk slice

Crosswalk implementation should follow the canonical Dolibarr Account Crosswalk Contract and ADR 0023:

  • keep BooksPlus authoritative for immutable target account identity and canonical account-role assignments;
  • consume stable Dolibarr source-account UUIDs rather than row ids or mutable codes;
  • retain explicit mapping versions and inclusive effective dates;
  • reject missing, stale, overlapping, ambiguous, wrong-scope, and ineligible mappings;
  • keep role projection distinct from BooksPlus AccountRoleAssignment;
  • publish or consume complete versioned snapshots with checksum validation; and
  • preserve attribution, reason, audit, and correlation evidence for protected crosswalk changes.