Run and monitor a batch posting job

Purpose

Staff submit batches together and follow a durable job through posting or refusal.

How It Works

Staff select batches for one unit and submit a posting request. The response identifies a durable job rather than completed ledger work. The job checks its batches and generates entries and schedules within its posting transaction. Staff follow progress and inspect the resulting batch states. Document problems can leave some batches in Error while independent batches post. A database refusal rolls back the whole transaction, and a failed job start can leave submitted work needing operational recovery.

Relationships

Prerequisite: Resolve posting accounts and retain their snapshots, which addresses the connected batch work.
Prerequisite: Produce document entries using the applicable accounting method, which addresses the connected batch work.
Related outcome: Use the batch’s permitted lifecycle actions, which addresses the connected batch work.
Related outcome: Inspect posting readiness before submission, which addresses the connected batch work.
Related outcome: Unpost a batch for correction and replacement posting, which addresses the connected batch work.
Related outcome: Plan deferred revenue and adjust its remaining releases, which addresses the connected batch work.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Submitted accounting work has a durable job and an identifiable completion or failure result.
Surfaces: consoleapijob
Constraints: Platform supplies durable-job execution and the progress record read by the console.
Intent sources: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-03services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-1services-accounting:docs/migrations/batch-posting/README.md#Merge readiness (Andrew's D7 of 2026-10-15: a refused posting fails)

Controls

30 controls apply, from the corpus control catalogue.

TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-IAM-006 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-CRY-004 TC-DAT-001 TC-DAT-004 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-AVL-001 TC-AVL-004 TC-MON-001 TC-MON-002 TC-MON-004 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005

Permissions

Key	Checked at	Scope
`accounting.batch-postings.post`	api	tenant

Business Rules

16 rules, 15 to be proved before approval. A rule's product intent is derived from its origin: 1 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	The posting permission governs submission and is included in the staff user tier. proved by `ATS-ACC-BAT-013-01`, `TST-ACC-BAT-008`, `TST-ACC-BAT-057`, `TST-ACC-BAT-076`	permission	api, console	test services-accounting:modules/batches/tests/e2e/batch-postings.e2e.spec.js#refuses a posting without the posting permission, 403
`02`must prove Proposed	Submission requires one to one hundred existing batches and a unit, rejects missing references before creating a job and defers mismatched-unit refusal to execution. proved by `ATS-ACC-BAT-013-01`, `ATS-ACC-BAT-013-26`, `TST-ACC-BAT-008`, `TST-ACC-BAT-057`, `TST-ACC-BAT-076`	validation	api, service	observed services-accounting:modules/batches/services/jobs/batch-posting-jobs.ts:createBatchJob; services-accounting:modules/batches/services/rules/batch-posting-rules.ts:ensureBatchesCanBePosted
`03`must prove Confirmed	Issuance creates no posting entry; submission returns a tracked job that generates entries during batch posting. origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#D-03 proved by `ATS-ACC-BAT-004-12`, `ATS-ACC-BAT-005-10`, `ATS-ACC-BAT-006-09`, `ATS-ACC-BAT-007-10`, `ATS-ACC-BAT-008-09`, `ATS-ACC-BAT-009-16`, `ATS-ACC-BAT-013-02`, `ATS-ACC-BAT-013-15`, `ATS-ACC-BAT-013-16`, `ATS-ACC-BAT-013-17`, `ATS-ACC-BAT-013-18`, `ATS-ACC-BAT-013-19`, `ATS-ACC-BAT-013-20`, `ATS-ACC-BAT-013-25`, `ATS-ACC-BAT-019-12`, `TST-ACC-BAT-007`, `TST-ACC-BAT-057`, `TST-ACC-BAT-075`, `TST-ACC-BAT-077`	lifecycle	service	test services-accounting:modules/batches/tests/e2e/batch-postings.e2e.spec.js#posts a batch as a durable job: the answer is the job, and the job posts the batch
`04`must prove Proposed	Repeating a request identity or requesting the same in-flight batch set returns the existing job, and a set still posted by a completed job returns that job, while post, unpost and repost form separate jobs. proved by `ATS-ACC-BAT-013-03`, `ATS-ACC-BAT-013-24`, `ATS-ACC-BAT-016-11`, `TST-ACC-BAT-076`, `TST-ACC-BAT-078`, `TST-ACC-BAT-125`	invariant	service, database	test services-accounting:modules/batches/tests/integration/services/jobs/submission-identity.integration.spec.js#answers a colleague's retry under another key, after the posting finished, with the job that posted (DEF-ACT-0514)
`05`must prove Proposed	The named Post action admits Open, Closed and Error; the engine additionally admits Verified and posting work unchanged for over five minutes, clears old errors and supports an environment override of its status check. proved by `ATS-ACC-BAT-013-04`	lifecycle	service	observed services-accounting:modules/batches/services/rules/batch-rules.ts:assertBatchCanBePosted; services-accounting:modules/batches/services/rules/batch-posting-rules.ts:ensureBatchesCanBePosted
`06`must prove Proposed	The named Post action checks an Open period before submission, bulk submission defers that check to execution, and execution holds the period shared until the posting transaction ends. proved by `ATS-ACC-BAT-012-04`, `ATS-ACC-BAT-013-05`, `ATS-ACC-BAT-013-21`, `TST-ACC-BAT-010`, `TST-ACC-BAT-070`	validation	service, database	observed services-accounting:modules/batches/services/actions/batch-actions.ts:postBatch; services-accounting:modules/batches/services/engine/engine-scope.ts:lockBatchesForPosting
`07`must prove Proposed	An update lock prevents both the named Post action and job execution until released. proved by `ATS-ACC-BAT-013-06`, `TST-ACC-BAT-063`, `TST-ACC-BAT-076`	policy	service	test services-accounting:modules/batches/tests/integration/services/jobs/batch-posting-record.integration.spec.js#is not posted by a job: the check step fails with the lock, and the batch stays open (DEF-ACT-0503)
`08`must prove Proposed	An ordinary posting job containing a system batch fails its check without posting anything. proved by `ATS-ACC-BAT-013-06`, `TST-ACC-BAT-063`, `TST-ACC-BAT-076`	policy	service	test services-accounting:modules/batches/tests/e2e/system-batches.e2e.spec.js#answers a posting naming the system batch with its job, and the job fails with the refusal
`09`must prove Proposed	A refused database write rolls back the complete posting transaction, fails the job and preserves the previous batch states without compensation. origin: services-accounting:docs/migrations/batch-posting/README.md#Merge readiness (Andrew's D7 of 2026-10-15: a refused posting fails) proved by `ATS-ACC-BAT-013-07`, `TST-ACC-BAT-077`	invariant	service, database	test services-accounting:modules/batches/tests/integration/services/jobs/deployed-task-handler.integration.spec.js#fails the job on a step the database refuses: refused once, recorded by the failure task, the batch open and nothing written
`10`must prove Proposed	Document-generation failures put their batch and affected downstream batches in Error without their entries, while independently valid batches in the request can still post. proved by `ATS-ACC-BAT-013-08`, `ATS-ACC-BAT-013-22`, `ATS-ACC-BAT-013-23`, `ATS-ACC-BAT-014-09`, `ATS-ACC-BAT-015-11`, `TST-ACC-BAT-011`, `TST-ACC-BAT-107`	lifecycle	service	test services-accounting:modules/batches/tests/integration/services/posting/rebuilt-posting-edges.integration.spec.js#posts January, puts April in error naming the application whose credit's batch is not posted, and May in error as April's dependent
`11`must prove Proposed	Successful posting records time, job and counts and base totals by document kind, including the money-document count and payments less refunds and payment reversals. proved by `ATS-ACC-BAT-002-08`, `ATS-ACC-BAT-013-09`, `ATS-ACC-BAT-013-14`, `TST-ACC-BAT-076`, `TST-ACC-BAT-105`, `TST-ACC-BAT-135`	calculation	service	test services-accounting:modules/batches/tests/integration/services/posting/rebuilt-documents.integration.spec.js#records the batch's statistics: the documents counted by kind and their base totals
`12`must prove Proposed	Posting deletes a batch with no documents regardless of the empty-batch option, whereas a batch containing only a voided payment posts without an entry. proved by `ATS-ACC-BAT-013-10`, `TST-ACC-BAT-008`, `TST-ACC-BAT-107`, `TST-ACC-BAT-114`	lifecycle	service	test services-accounting:modules/batches/tests/integration/services/posting/rebuilt-posting-edges.integration.spec.js#posts February with its one entry, and June is gone (RS-1116)
`13`must prove Proposed	Only one current posting can exist, so a competing direct posting waits and then rejects the batch already posted without another write. origin: services-accounting:docs/architecture/accounting-2.0/02-decisions.md#A-1 proved by `ATS-ACC-BAT-013-11`, `TST-ACC-BAT-096`	invariant	service, database	test services-accounting:modules/batches/tests/integration/services/posting/concurrent-posting.integration.spec.js#makes a direct posting wait for the batch, then refuse it as posted, with no posting and no entry written
`14` Proposed	Progress presents checking and writing steps with checked, generated and written events and a completion description. proved by `ATS-ACC-BAT-013-02`, `TST-ACC-BAT-007`, `TST-ACC-BAT-057`, `TST-ACC-BAT-075`, `TST-ACC-BAT-077`	policy	service, console	test services-accounting:modules/batches/tests/integration/services/jobs/batch-posting-job.integration.spec.js#records the posting's progress on its history: the batch checked, its entries generated and written, one event each, climbing to 99 before the write step completed
`15`must prove Proposed	Description text cannot activate legacy test directives or alter posting behavior. proved by `ATS-ACC-BAT-013-12`, `TST-ACC-BAT-024`, `TST-ACC-BAT-076`	policy	service	test services-accounting:modules/batches/tests/integration/services/jobs/batch-posting-record.integration.spec.js#posts a batch whose description is a 1.0 test directive, as any other (DEF-ACT-0512)
`16`must prove Proposed	The registered posting and unposting jobs disable user retry and cancellation while their workflow tasks retain separate retry settings. proved by `ATS-ACC-BAT-013-13`	policy	service	observed services-accounting:modules/batches/services/jobs/batch-posting-jobs.ts:ensureBatchPostingJobTypesRegistered

Scenarios

Id	Given	When	Then	Provenance
`01`	A Closed batch is ready for posting.	Staff confirm Post.	The progress display reaches completion, the batch becomes Posted and its ledger totals balance.	documented services-accounting:docs/milestones/walkthroughs/ACCT-M3-handoff.md#Start here (step 4)
`02`	Two staff members are viewing the same Closed batch.	They submit posting concurrently.	One posting is written, with the other caller receiving the existing job or an already-posted refusal.	test react-console:acceptance/accounting/playwright/journeys/batches-posting/ACT-ACC-0519.spec.ts#ACT-ACC-0519
`03`	One batch is valid and another needs an unconfigured account.	The posting job runs for both.	The independent valid batch posts, the other records its document error and the job can still succeed.	test react-console:acceptance/accounting/playwright/journeys/batches-posting/ACT-ACC-0521.spec.ts#ACT-ACC-0521

Planning

Implementation

Run and monitor a batch posting job ​

Purpose ​

How It Works ​

Relationships ​