--- id: SVC-ACC-CLS-fiscal-close title: Fiscal Close Service Module product_area: accounting module: close repository: services-accounting source_module: modules/fiscal-close revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-ACC-CLS-001 - DOM-ACC-CLS-002 - DOM-ACC-CLS-003 - DOM-ACC-CLS-004 does_not_own: - >- Books maintains calendar identity, dates, business units and the settings row. Close owns the period’s closing state and consumes its bank-verification policy. - >- Batch management supplies posting guards, system batches and the recognition schedules used by execution. - >- Transactions supplies the inspected financial documents and the aging report type. - >- Reconciliation supplies payment findings and the placement of eligible late effects. - >- Platform supplies durable execution, aging infrastructure, permission evaluation and person-name lookup. - >- Accounting Maintenance exposes close export and deletion participation to Platform’s workspace lifecycle. operations: - operation_id: listFiscalClosePeriods intent: >- Read a selected business unit’s years and months in date order, including closing state, attribution, run backlink, reopen count and current designation. access: console permission: accounting.fiscal-periods.read realises: - CAP-ACC-CLS-001 - CAP-ACC-CLS-002 - CAP-ACC-CLS-010 published_to_submissions: 'not published: calendar retrieval has no submission payload.' - operation_id: getFiscalCloseReadiness intent: >- Calculate the selected month’s read-only readiness, with optional year checks, payment context, verdict and closing-effects preview. access: console permission: accounting.fiscal-periods.read (evaluates accounting.fiscal-periods.close) realises: - CAP-ACC-CLS-004 - CAP-ACC-CLS-005 - CAP-ACC-CLS-006 - CAP-ACC-CLS-007 - CAP-ACC-CLS-010 published_to_submissions: 'not published: readiness is a calculated read rather than customer intake.' - operation_id: getFiscalCloseAuthorization intent: >- Check whether the caller’s action grants and the current calendar sequence allow closing or reopening the month, prioritizing permission explanations. access: console permission: >- accounting.fiscal-periods.read (evaluates accounting.fiscal-periods.close and accounting.fiscal-periods.reopen) realises: - CAP-ACC-CLS-002 published_to_submissions: 'not published: the response describes the caller’s current authority.' - operation_id: closeFiscalPeriod intent: >- Accept a command-keyed month close, choosing year-close kind for the final month, commit its request with a job and start execution after commit. access: console permission: accounting.fiscal-periods.close realises: - CAP-ACC-CLS-008 - CAP-ACC-CLS-009 - CAP-ACC-CLS-010 - CAP-ACC-CLS-015 published_to_submissions: >- not published: the proposed boundary reserves changes to closed books for authorized accounting commands. - operation_id: reopenFiscalPeriod intent: >- Accept a command-keyed correction of the eligible latest closed month with a reason, committing its request and execution job together. access: console permission: accounting.fiscal-periods.reopen realises: - CAP-ACC-CLS-011 - CAP-ACC-CLS-009 published_to_submissions: >- not published: correcting the closed books is an authorized accounting command. - operation_id: listFiscalCloseRuns intent: >- Read a newest-first page of close and reopen requests, with optional unit, year, kind and outcome filters. access: console permission: accounting.fiscal-periods.read realises: - CAP-ACC-CLS-013 published_to_submissions: 'not published: history retrieval collects no new submission.' - operation_id: getFiscalCloseRun intent: >- Read the selected request with period context, ordered task outcomes, cumulative attempts, errors, produced-record links, events and retained readiness. access: console permission: accounting.fiscal-periods.read realises: - CAP-ACC-CLS-013 - CAP-ACC-CLS-012 published_to_submissions: 'not published: execution inspection collects no new submission.' - operation_id: retryFiscalCloseRun intent: >- Create a linked execution attempt for a failed request that retains its month and resume remaining work. access: console permission: >- accounting.fiscal-periods.read, then accounting.fiscal-periods.close or accounting.fiscal-periods.reopen by the run's kind realises: - CAP-ACC-CLS-012 published_to_submissions: >- not published: recovery acts on a saved request and has no intake contract. - operation_id: cancelFiscalCloseRun intent: >- Cancel an eligible queued or failed request and restore a retained month’s previous state, refusing restoration after completed recognition or reversal. access: console permission: >- accounting.fiscal-periods.read, then accounting.fiscal-periods.close or accounting.fiscal-periods.reopen by the run's kind realises: - CAP-ACC-CLS-012 published_to_submissions: >- not published: cancellation acts on a saved request and has no intake contract. - operation_id: getFiscalCloseRecord intent: >- Read a close’s retained snapshot with its request, payment evidence, exception participants and linked correction history. access: console permission: accounting.fiscal-periods.read realises: - CAP-ACC-CLS-014 published_to_submissions: 'not published: retained-evidence retrieval has no submission payload.' events: - name: fiscal_close.readiness_blocked direction: produced when: Revalidation records required checks that block execution. payload_summary: >- The job-local history receives the blocking check references, outcomes and explanations; no domain bus publication is declared. - name: fiscal_close.warnings_unacknowledged direction: produced when: >- The binding calculation has warning outcomes absent from the request’s acknowledgements. payload_summary: >- The job-local history receives unacknowledged warning references without preventing execution. - name: fiscal_close.step_skipped direction: produced when: 'Recognition, reversal or the cost of goods sold task records skipped work.' payload_summary: The job-local history identifies the skipped task and its reason. - name: fiscal_close.snapshot_waiting direction: produced when: >- An active aging run prevents finalization and another attempt is requested. payload_summary: The job-local history retains the aging library’s active-run message. - name: fiscal_close.period_reopened direction: produced when: Reopen finalization has committed the open month. payload_summary: >- The later history transaction records requester, reason and incremented reopen count. - name: fiscal_close.run_cancelled direction: produced when: An eligible cancellation commits its final run outcome. payload_summary: >- The cancellation transaction records the acting caller and period-state effect. jobs: - >- fiscal_period_close uses the accounting-fiscal-close-close machine: publish the task catalogue, lock, revalidate, recognize_revenue, book_cogs, finalize and roll_forward. Finalization repeats after sixty-second waits while aging is active, within sixty iterations. Tasks use the imported standard retry and five-to-fifteen-minute task limits; the failure task has its own declared retry. - >- fiscal_period_reopen uses the accounting-fiscal-close-reopen machine: publish the task catalogue, lock, reverse_revenue and finalize, with a declared failure task. - >- Job start delegates failures to the imported leave-to-reconciler helper; job-kind registration exposes a settled-failure callback. Platform’s reconciler implementation is not among the pinned sources. integrations: - system: 'Batch management (in-process, same service)' direction: outbound contract: >- The revenue port calls recognition then system-batch posting under a close-run-derived key; reversal unrecognizes period entries and reverses the original keyed batch. Batch management enforces the system operation’s permitted period states. - system: 'Reconciliation (in-process, same service)' direction: outbound contract: >- The evaluation reads assessReconciliationReadiness within its transaction, sharing one assessment per month and retaining supplied findings. - system: 'Books (in-process, same service)' direction: outbound contract: >- The module reads the calendar, business unit and verification setting, and invokes generateFiscalYears one year at a time after close success. - system: Platform snapshot library (receivables aging) direction: outbound contract: >- Finalization calls requestSnapshotRun for accounting.ar_aging with a period_close trigger, superseding version and calendar month end. It records the known-at instant and chooses finalized or reconstructed from other units’ overlapping periods. - system: Platform durable jobs and Step Functions direction: outbound contract: >- The module declares job kinds, linked retry creation and after-commit start. State-machine task operations are hosted by the batch-posting task function. - system: Platform workspace lifecycle (through Accounting Maintenance) direction: inbound contract: >- The accounting.fiscal_close dataset exports through Accounting Maintenance; the accounting.fiscal-close purge participant declares configuration as its prerequisite. consistency: - rule: >- Acceptance saves the request and first job in one transaction before starting execution; matching command replay returns the stored run without another start. kind: transactional compensation: >- Transaction rollback prevents a partial request; failed starts use the delegated reconciler helper while the run waits. - rule: >- Period-changing tasks commit domain changes and run output together, but replay can bypass locking; history events and calendar generation commit separately. kind: transactional compensation: >- Domain rollback cannot undo an earlier committed result when its later history append fails. - rule: >- Revalidation calculates readiness under the period lock and commits a blocking evaluation with release and run failure. kind: transactional compensation: >- Opening the month compensates for taking it; the stored refusal remains as evidence. - rule: >- Finalization commits the closed month, snapshot, aging request and successful run together; an active aging run rolls the transaction back. kind: transactional compensation: >- Rollback retains closing state for another attempt or settled-failure handling. - rule: >- Recognition commits before closure, so a later failure can retain a protected month with revenue already posted. kind: eventual compensation: >- Recovery proceeds by retry, followed by reopen if reversal is wanted; cancellation refuses completed recognition. - rule: >- Calendar maintenance generates each year in its own transaction after run success and stores its task output after the loop. kind: eventual compensation: >- Committed years remain and the successful close is retained; later attempts recalculate missing years. - rule: >- The failure callback records a current-job failure and releases a finalization failure without completed recognition, using a run read made before acquiring the period lock. kind: eventual compensation: >- The callback has replay guards, but stale reads during a recovery race prevent claiming unconditional current-job serialization. evidence: - >- services-accounting at f47cb263: modules/fiscal-close/aws/api/fiscal-close.routes.ts, fiscal-period-close.routes.ts, fiscal-close.schemas.ts; aws/logic/fiscal-close.step-functions.ts; services/jobs/*.ts; services/ports/*.ts; services/runs/close-run-view.ts; export/*.ts; aws/accounting.service.ts:FiscalPeriodActions, FiscalPeriodsPermissions; modules/maintenance/services/participants/fiscal-close-participant.ts; docs/architecture/accounting-2.0/03-module-structure.md. - >- react-console at baf6dae3: lib/accounting/close/http-service.ts (the operations the console calls). 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-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] --- # Fiscal Close Service Module ## What This Service Is For Finance staff use this service to review monthly readiness, close the books, reopen eligible months and inspect retained evidence. Durable jobs carry out the financial sequence while the request remains available for progress and recovery. The module makes no model calls. ## Boundary Close owns period-closing fields, readiness, runs, their jobs and immutable close snapshots. It calls the calendar, posting, financial-document and reconciliation owners within Accounting. Platform supplies execution and aging infrastructure. Deployment currently places reads and recovery in Reconciliation, submissions in Books configuration and tasks in batch posting. No separate close function is declared. ## Operations in Words Calendar and authorization reads establish the subject and available actions. Readiness calculates a fresh review without independently writing records. Close and reopen submissions validate authority, request shape and calendar sequence, then save a request with its execution job. The API returns ordinary success with a run; asynchronous acceptance status is not declared. History operations list requests and assemble one request’s task history or close record. Recovery retries retained failed work or cancels an eligible waiting or failed request. Its action grant depends on the request kind. Every operation records an unpublished Submissions reason; publication policy remains subject to verification of the external standard. ## Events and Jobs Two declared state machines execute close and reopen task catalogues. The module has no owned queue or schedule and declares no domain event-bus publication. Its events are job-local history. Several are appended after their domain transaction and can therefore be absent after a post-commit failure. Infrastructure alarms observe failed or timed-out executions; customer attention and notifications are not produced here. ## Consistency Guarantees Recognition and reversal retain their domain results with run output. Finalization atomically closes the month, captures evidence, accepts an aging request and succeeds the run. Aging contention can prevent that transaction from committing. Calendar maintenance and job history have separate commit boundaries. Period locks protect one month’s changing work; neighbouring sequence reads and the failure callback’s pre-lock run read need stronger concurrency proof.