--- id: SVC-ACC-BAT-batches title: Batches Service Module product_area: accounting module: batches repository: services-accounting source_module: modules/batches revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-ACC-BAT-001 - DOM-ACC-BAT-003 - DOM-ACC-BAT-004 - DOM-ACC-BAT-005 does_not_own: - >- Books supplies financial entities, calendars, account and dimension definitions, currencies and unit accounting policy. - >- Products supplies product accounting configuration, deferral strategies and revenue allocation. - >- Transactions controls source documents and their business lifecycles; posting controls the accounting snapshots stored on their lines. - >- Month-end Close controls period orchestration and calls system-accounting functions within its transaction. - >- Accounting maintenance controls owned scheduling storage and dispatch, lifecycle participants and the workspace export plan. - >- Platform controls authorization, durable job presentation, attention delivery and responsibility, and query serving. operations: - operation_id: getBatchesHealth intent: Return deployment and build health for the batch HTTP function. access: public permission: >- none: public health route (the operation name follows the getHealth pattern of the shared health route) realises: [] published_to_submissions: 'not published: infrastructure health does not accept business intake.' - operation_id: createBatch intent: >- Create an Open business-unit collection with date-derived fiscal placement and optional scheduled close. access: console permission: accounting.batches.create realises: - CAP-ACC-BAT-001 - CAP-ACC-BAT-005 published_to_submissions: 'not published: finance staff create collections as internal work.' - operation_id: listBatches intent: >- Read paged collections with current figures, using business-unit, status and fiscal filters. access: console permission: accounting.batches.read realises: - CAP-ACC-BAT-002 published_to_submissions: 'not published: collection inspection is a read.' - operation_id: getDependentBatches intent: >- Traverse recorded collection dependencies and return eligible Posted, Downloaded or Error dependents. access: console permission: accounting.batches.read realises: - CAP-ACC-BAT-002 - CAP-ACC-BAT-016 published_to_submissions: 'not published: dependency inspection is a read.' - operation_id: getBatch intent: Retrieve one collection with its current aggregate figures. access: console permission: accounting.batches.read realises: - CAP-ACC-BAT-002 published_to_submissions: 'not published: collection retrieval is a read.' - operation_id: updateBatch intent: >- Patch permitted details and system protection, optionally checking the submitted version; ordinary patches cannot set lifecycle, unit or stream. access: console permission: accounting.batches.update realises: - CAP-ACC-BAT-003 - CAP-ACC-BAT-005 published_to_submissions: 'not published: staff correct existing internal work.' - operation_id: closeBatch intent: Finish intake on an Open collection and synchronize enabled attention. access: console permission: accounting.batches.update realises: - CAP-ACC-BAT-004 published_to_submissions: 'not published: retirement is a lifecycle command.' - operation_id: reopenBatch intent: >- Restore intake for Closed, Verified or Error work and remove carried errors. access: console permission: accounting.batches.update realises: - CAP-ACC-BAT-004 published_to_submissions: 'not published: restoration is a lifecycle command.' - operation_id: archiveBatch intent: Retire Open or Closed work from ordinary intake and posting. access: console permission: accounting.batches.update realises: - CAP-ACC-BAT-004 published_to_submissions: 'not published: archiving is a lifecycle command.' - operation_id: unarchiveBatch intent: Restore archived work as Open. access: console permission: accounting.batches.update realises: - CAP-ACC-BAT-004 published_to_submissions: 'not published: archive restoration is a lifecycle command.' - operation_id: listBatchActions intent: >- Describe service-derived actions for the caller, including lock-related disabled explanations. access: console permission: >- accounting.batches.read (also evaluates accounting.batches.update, accounting.batch-postings.post, accounting.batch-postings.unpost) realises: - CAP-ACC-BAT-004 published_to_submissions: 'not published: action discovery is a read.' - operation_id: performBatchAction intent: >- Execute the requested named lifecycle action; Post and Unpost prepare a batch-locked durable submission. access: console permission: >- accounting.batches.read to reach the handler, then the action's own key (accounting.batches.update, accounting.batch-postings.post or accounting.batch-postings.unpost) realises: - CAP-ACC-BAT-004 - CAP-ACC-BAT-013 - CAP-ACC-BAT-016 published_to_submissions: 'not published: named commands complete existing accounting work.' - operation_id: deleteBatch intent: >- Remove an eligible unreferenced collection and its owned close schedule, resolving enabled attention. access: console permission: accounting.batches.delete realises: - CAP-ACC-BAT-006 published_to_submissions: 'not published: removal operates on existing accounting work.' - operation_id: createRecurringBatch intent: >- Save stream configuration and its schedule, attempting first intake creation when active. access: console permission: accounting.recurring-batches.create realises: - CAP-ACC-BAT-009 published_to_submissions: 'not published: stream creation is configuration.' - operation_id: listRecurringBatches intent: >- Read stream configuration pages filtered by business unit, activity or search. access: console permission: accounting.recurring-batches.read realises: - CAP-ACC-BAT-009 published_to_submissions: 'not published: stream discovery is a read.' - operation_id: getRecurringBatch intent: >- Retrieve stream configuration together with scheduler-derived next occurrence, latest outcome and pause metadata. access: console permission: accounting.recurring-batches.read realises: - CAP-ACC-BAT-009 published_to_submissions: 'not published: stream retrieval is a read.' - operation_id: updateRecurringBatch intent: >- Replace versioned stream configuration and schedule settings, attempting first intake on reactivation. access: console permission: accounting.recurring-batches.update realises: - CAP-ACC-BAT-009 published_to_submissions: 'not published: stream replacement is configuration.' - operation_id: deleteRecurringBatch intent: >- Remove unreferenced stream configuration, owned scheduling history and an eligible unused intake collection. access: console permission: accounting.recurring-batches.delete realises: - CAP-ACC-BAT-009 published_to_submissions: 'not published: stream removal is configuration.' - operation_id: listRecurringBatchRuns intent: Read reverse-chronological occurrence outcomes for a stream. access: console permission: accounting.recurring-batches.read realises: - CAP-ACC-BAT-010 published_to_submissions: 'not published: run-history inspection is a read.' - operation_id: previewRecurringBatchRoll intent: Calculate the next occurrence plan without creating intake. access: console permission: accounting.recurring-batches.read realises: - CAP-ACC-BAT-010 published_to_submissions: 'not published: occurrence planning is a nonmutating read.' - operation_id: getBatchAssignmentSettings intent: Retrieve a business unit routing fallback and ordered criteria. access: console permission: accounting.batch-assignment-settings.read realises: - CAP-ACC-BAT-011 published_to_submissions: 'not published: routing inspection is a read.' - operation_id: saveBatchAssignmentSettings intent: >- Atomically replace routing configuration and its priority-ordered rule collection. access: console permission: accounting.batch-assignment-settings.update realises: - CAP-ACC-BAT-011 published_to_submissions: 'not published: routing replacement is configuration.' - operation_id: deleteBatchAssignmentSettings intent: Remove routing configuration with its rule children. access: console permission: accounting.batch-assignment-settings.delete realises: - CAP-ACC-BAT-011 published_to_submissions: 'not published: routing removal is configuration.' - operation_id: evaluateBatchAssignment intent: Evaluate supplied document facts against saved routing without mutation. access: console permission: accounting.batch-assignment-settings.read realises: - CAP-ACC-BAT-011 published_to_submissions: 'not published: example evaluation is nonmutating.' - operation_id: postBatches intent: >- Accept an HTTP submission of one to one hundred batch identifiers for durable posting; execution validates their requested unit. access: console permission: accounting.batch-postings.post realises: - CAP-ACC-BAT-013 - CAP-ACC-BAT-014 - CAP-ACC-BAT-015 - CAP-ACC-BAT-019 published_to_submissions: 'not published: posting completes internal accounting work.' - operation_id: unpostBatches intent: >- Accept a bounded durable recovery submission for ordinary ledger deletion and collection restoration. access: console permission: accounting.batch-postings.unpost realises: - CAP-ACC-BAT-016 published_to_submissions: 'not published: unposting is administrative accounting recovery.' - operation_id: previewBatchPostings intent: >- Invoke the accounting task synchronously to inspect up to one hundred collections without committing accounting. access: console permission: accounting.batch-postings.preview realises: - CAP-ACC-BAT-012 published_to_submissions: 'not published: posting preview is nonmutating inspection.' - operation_id: listSubledgerEntries intent: >- Read ledger pages using accounting filters, limiting to current generations unless history is requested. access: console permission: accounting.subledger-entries.read realises: - CAP-ACC-BAT-018 published_to_submissions: 'not published: ledger listing is a read.' - operation_id: getSubledgerEntry intent: Retrieve one ledger header and its ordered lines. access: console permission: accounting.subledger-entries.read realises: - CAP-ACC-BAT-018 published_to_submissions: 'not published: ledger retrieval is a read.' - operation_id: describeInvoiceLineRevenue intent: >- Describe current invoice-line revenue plans, releases and deferred position. access: console permission: accounting.subledger-entries.read realises: - CAP-ACC-BAT-019 published_to_submissions: 'not published: revenue-plan inspection is a read.' - operation_id: postSystemBatch intent: >- Create or reuse fiscal system accounting within the caller transaction, using the event key for identical-request reuse. access: internal permission: >- none: called in-process inside fiscal close's transaction, which fiscal close authorizes realises: - CAP-ACC-BAT-020 published_to_submissions: 'not published: fiscal orchestration calls this function in-process.' - operation_id: reverseSystemBatch intent: >- Retire a fiscal system generation within the caller transaction by appending mirrors and restoring its collection. access: internal permission: 'none: called in-process inside fiscal close''s transaction' realises: - CAP-ACC-BAT-020 published_to_submissions: 'not published: fiscal reopening calls this function in-process.' - operation_id: recogniseDueEntries intent: >- Release due business-unit revenue-plan entries into fiscal accounting within the caller transaction. access: internal permission: 'none: called in-process inside fiscal close''s transaction' realises: - CAP-ACC-BAT-019 - CAP-ACC-BAT-020 published_to_submissions: 'not published: fiscal recognition is an in-process accounting seam.' - operation_id: unrecogniseEntries intent: >- Take back affected fiscal recognition within the reopening caller transaction. access: internal permission: 'none: called in-process inside fiscal close''s transaction' realises: - CAP-ACC-BAT-020 published_to_submissions: 'not published: fiscal restoration is an in-process accounting seam.' - operation_id: defaultBatchFor intent: >- Select intake for native document creation using saved routing; pro forma selection may be empty. access: internal permission: >- none: document callers authorize their own operation before in-process selection realises: - CAP-ACC-BAT-011 - CAP-ACC-BAT-007 published_to_submissions: 'not published: document creation uses internal default selection.' events: - name: accounting.batches_awaiting_posting attention item direction: produced when: >- Enabled transaction-batch writes publish waiting Closed, Verified, Posting and Error work, refresh it while waiting, and resolve retirement outcomes. Sweep repair refreshes or clears items. payload_summary: >- The item identifies the collection and business-unit scope, posting responsibility, readable reference, document count, period end and allowance-derived due date; its definition declares bulk posting. - name: job.step.progress (posting and unposting jobs) direction: produced when: The task emits collected per-batch stage progress after accounting commit. payload_summary: >- Fixed-format messages carry percentages, collection reference, processing stage, document-kind counts and base amount for console interpretation. - name: accounting.batch.auto-close occurrence direction: consumed when: >- The scheduler delivers the configured single close occurrence for an Open collection. payload_summary: 'Owned schedule identity, occurrence time and collection subject.' - name: accounting.recurring-batch.roll occurrence direction: consumed when: The scheduler delivers an active stream occurrence. payload_summary: 'Owned schedule identity, occurrence time and recurring-stream subject.' jobs: - >- batch_posting executes through accounting-batch-posting-post on the accounting task function, publishing phases before PostBatches and invoking failure handling when needed; user retry and cancellation are disabled. - >- batch_unposting executes through accounting-batch-posting-unpost on the shared accounting task function. - >- accounting.batch.auto-close is maintenance-dispatched work that retires intake and prepares accounting in the retirement transaction. - >- accounting.recurring-batch.roll opens successor intake, retires its predecessor and prepares eligible predecessor accounting. - >- Hourly attention maintenance uses a separate function with reserved concurrency one; disabling publishing suppresses Platform writes while Accounting traversal still runs. - >- The shared task deployment also serves the two fiscal workflows, whose orchestration belongs to Month-end Close. integrations: - system: Platform durable jobs direction: outbound contract: >- Accounting stores the registered job roots, phases and events for Platform presentation. Submission starts Step Functions after commit; no posting reconciler is registered. - system: Platform attention direction: outbound contract: >- Enabled business transactions call the gated publisher. The pinned context enables development attention and disables production attention. - system: Platform query layer direction: outbound contract: >- Read-only collection, ledger-line and revenue-release registrations have separate query permissions and workspace-scoped data, with supporting ledger and waterfall recipes. - system: Platform workspace lifecycle direction: inbound contract: >- Accounting participants remove dependent records through guarded ledger purge and ordered table steps. The module contributes three workspace-export datasets; historical cut-off accuracy remains disputed. - system: Month-end Close direction: inbound contract: >- The four recognition and system-generation functions require the fiscal caller transaction and reject calls outside it. - system: Transactions direction: inbound contract: >- Document creation uses collection reads, default selection and intake checks; generation reads source documents and persists account snapshots within accounting execution. - system: Books and Products direction: outbound contract: >- Posting consumes financial-entity, protected-period, account, tax-payable and product-accounting configuration through in-process reads. consistency: - rule: >- Generation history, ledger, plans, line snapshots and batch outcomes share the accounting transaction. kind: transactional compensation: >- Transactional refusal rolls back accounting; no compensating generation is implemented. - rule: >- Ordinary recovery removes current ledger rows, retires Open plans and restores intake in one transaction. kind: transactional compensation: >- Deletion refusal rolls back recovery; already recognised fiscal releases are not automatically reversed. - rule: >- Scheduled retirement and its prepared posting submission commit together, before separate workflow start. kind: eventual compensation: No start reconciler exists; failed start can leave a Pending submission. - rule: >- Enabled attention publication shares the originating collection transaction. kind: transactional compensation: >- The hourly repair pass refreshes or clears drift; disabled publishing leaves catch-up work. - rule: Routing fallback and its ordered rules change as one atomic replacement. kind: transactional compensation: Rejected replacement leaves the prior routing record and rules intact. - rule: >- Fiscal system generation, recognition and orchestration state use the fiscal caller transaction. kind: transactional compensation: >- A refused accounting write aborts the fiscal transaction without later compensation. - rule: >- Operational progress and required phase settlement follow accounting commit. kind: eventual compensation: >- Settlement failure can coexist with committed accounting; advisory progress failure is logged. evidence: - >- services-accounting at f47cb263: modules/batches/aws/api/*.routes.ts, *.schemas.ts; aws/batches.module.ts; aws/logic/*.ts; services/**; attention/batches-awaiting-posting.attention.ts; aws/accounting.service.ts (batch permission groups); aws/cdk.json; lib/attention.ts; docs/migrations/batch-posting/DESIGN.md; docs/accounting/*.md - >- react-console at baf6dae3: lib/accounting/transactions/http/batches.ts, batch-posting.ts, batch-delivery.ts, http-service.ts; lib/accounting/configuration/client.ts - >- services-accounting:modules/batches/services/assignment/default-batch.ts:defaultBatchFor; modules/transactions/services/batches-for-documents.ts controls: [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-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-SEC-001, TC-SEC-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-004, TC-DAT-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-006, TC-AVL-001, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AVL-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005] --- # Batches Service Module ## What This Service Is For Batch Management connects document collection to accounting completion. It supplies intake configuration, durable posting and ordinary recovery, ledger inspection, revenue plans and fiscal accounting seams. It performs no inference. ## Boundary The owned domain objects define the collection and accounting records controlled here. Neighboring Accounting modules supply source documents and financial configuration, while fiscal orchestration owns period completion. Platform and Accounting maintenance provide the delegated execution, query, attention and lifecycle infrastructure. ## Operations in Words The operation rows group collection commands, stream and routing configuration, durable execution, accounting inspection and internal fiscal functions. They retain exact authorization keys and planning-capability homes. Default selection is an internal document-creation function, and each operation records its current absence of Submissions publication. ## Events and Jobs Scheduled occurrences enter through maintenance dispatch. The accounting task publishes watched job progress after its business commit, while enabled attention synchronizes waiting work and repairs it hourly. Fiscal orchestration shares the task deployment without transferring its ownership to this module. ## Consistency Guarantees The consistency rows distinguish atomic business changes from later operational completion. Neither a successful preview nor a final job label replaces inspection of accounting state. Dependency recovery, recognised revenue and historical export remain qualified by findings.