Last reviewed: 2026-07-04

Summary Accounting Batch Contract

Canonical object: SummaryAccountingBatch

Canonical child concepts: - SummaryAccountingValidationIssue - SummaryAccountingEvidenceLink - SummaryAccountingPreparedJournalEntryPreview - SummaryAccountingPostingResultLink

Required concepts: - id - company id - summary batch number - actor id - workflow family or summary type - target financial period when known - source system - external event identity - idempotency key - source-world event date or date range - BooksPlus acceptance time - source payload hash when available - normalized meaning hash - status - validation issues - evidence links - prepared journal-entry preview - posting-result links - created timestamp - updated timestamp

Allowed statuses: - staged - held_for_review - ready_to_post - posted - abandoned

Validation issue severities: - warning - error

Protected actions: - summary_accounting_batch.stage - summary_accounting_batch.mark_ready - summary_accounting_batch.abandon - summary_accounting_batch.post

Rules: - Summary batches are workflow staging and review records. - Summary batches are not formal report truth. - Staging a summary batch requires company and actor context, ordinary authorization through summary_accounting_batch.stage, and an append-only audit event. - summary_accounting_batch.stage does not require a reason or step-up confirmation because staging creates review state and no ledger effect. - Summary batch identity is scoped by company. - Human-visible summary batch numbers are required for summary batches. - Summary batch numbers must be unique within a company, assigned by BooksPlus intake, positive, increasing for created batches, and immutable after assignment. - The standard display format is SA- followed by the company-scoped number padded to at least six digits, such as SA-000001. - Summary batch number is a human-facing reference and lookup value. Batch identity remains stable by id for persistence, audit, imports, idempotency, correction, recovery, and support. - Summary batch number is not part of normalized source meaning and must not affect idempotent replay evaluation. - Mutating summary batch actions must emit batch-level audit events with target_type = summary_accounting_batch and target_id set to the summary batch id. - Summary batch audit event reason text must use the human-visible summary batch number while preserving durable identity in target_id. - Machine or file intake that can affect accounting workflows requires source system identity and an idempotency key. - A replay with the same company, source system, and idempotency key may be treated as idempotent only when the normalized meaning hash matches the accepted batch. - Conflicting reuse of an idempotency key must be rejected or held for review. - Conflicting imports must not silently overwrite accepted meaning. - BooksPlus acceptance time is stamped by BooksPlus, not supplied by the source system. - Source-world dates describe the external activity and must not replace BooksPlus acceptance time. - Validation issues must preserve severity, field or scope when applicable, message, and review meaning. - Error issues block ready-to-post status until resolved by an explicit review or replacement flow. - Warning issues may require review but do not automatically block ready-to-post status. - Readiness evaluation must identify the current status, the permitted next state-machine transition, and the reason that ready_to_post is allowed or blocked. - Readiness reason codes are stable domain/presentation output and are not persisted as summary batch fields. - Readiness evaluation must include a compact "why not ready" summary for user-facing review. This summary is derived output, is not persisted as a summary batch field, and must not replace detailed validation issues. - Evidence links must reference Source Documents when business evidence identity is needed. - Superseded Source Documents must not support new routine posting evidence. - Prepared journal-entry previews are candidates for review, not journal entries. - Prepared journal-entry previews must preserve the information needed to build a central Accounting posting request. - Prepared journal-entry preview lines preserve immutable account ids, but review and drilldown displays must show account code and name when the account can be resolved. - Posting-result links must reference journal entries and audit events created by the central Accounting posting path. - Posting-result displays must show the posted journal entry number when the linked journal entry can be resolved. - Posting-result links still preserve durable journal entry ids and audit event ids; unresolved journal entry links must display a shortened internal id rather than a full GUID. - Posting a summary batch must use the protected action summary_accounting_batch.post for the batch workflow and the existing Accounting posting path for ledger effects. - A user-facing Approve and Post action may be exposed for a staged batch only when readiness permits staged -> ready_to_post; it must internally perform summary_accounting_batch.mark_ready before summary_accounting_batch.post and must preserve both protected-action decisions and audit events. - Summary posting screens must present an inline preview of evidence, prepared journal-entry lines, totals, readiness, and posting outcome before the user completes a posting action. - A posted summary batch must not be silently mutated. - Posted accounting records are corrected through reversal or adjustment, not by editing summary batches. - Abandoned batches remain review history and must not be deleted merely because they were not posted.

Validation expectations: - persisted status, severity, and protected action values use stable snake_case contract values. - company, actor, source system, idempotency key, and BooksPlus acceptance time are present for accepted machine or file intake. - summary_batch_number is present, positive, immutable, and unique within the company. - normalized meaning hash is present before idempotent replay evaluation. - conflicting idempotency reuse is visible as rejection or held-for-review state. - ready-to-post batches have no unresolved error issues. - mutating summary batch actions emit batch-level audit events with company, actor, action, target, result, and reason when applicable. - preview rows do not create journal entries, audit events, source documents, or ledger effects by themselves. - posting-result links point to durable posted journal entries and their audit events.

Related truth pages: - ../accounting/summary-accounting.md - ../accounting/posting-and-reversal.md - ../accounting/source-documents.md - journal-entry.contract.md - source-document.contract.md - financial-period.contract.md - security/protected-action-contract.md - security/audit-event-contract.md

Related decisions: - ../decisions/accepted/0007-provider-agnostic-import-boundaries.md - ../decisions/accepted/0020-initial-release-scope-and-financial-workflow-taxonomy.md