Rhythm 2.0 Specifications

Appearance

CAP-ACC-CLS-008Complete a guarded month-end close

Markdown

CAP-ACC-CLS-008

Complete a guarded month-end close

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationPartially observed

Planning

Feature
FEAT-ACC-CLS-03
Exercised by
FAS-ACC-CLS-03-01, FAS-ACC-CLS-03-02, FAS-ACC-CLS-03-03, FAS-ACC-CLS-03-04, FAS-ACC-CLS-03-05, JNY-ACC-CLS-005
Key concepts
CON-ACC-CLS-003, CON-ACC-CLS-001
Actors
ACT-ACC-015, ACT-ACC-016
Journeys
JNY-ACC-CLS-001, JNY-ACC-CLS-002, JNY-ACC-CLS-003, JNY-ACC-CLS-004
Depends on
CAP-ACC-CLS-002, CAP-ACC-CLS-004
Related
CAP-ACC-CLS-003, CAP-ACC-CLS-009, CAP-ACC-CLS-010, CAP-ACC-CLS-012, CAP-ACC-CLS-014, CAP-ACC-CLS-015
Open questions
OQ-ACC-CLS-001
Proved by
ATS-ACC-CLS-008

Implementation

Executable suites
TST-ACC-CLS-001, TST-ACC-CLS-004, TST-ACC-CLS-005, TST-ACC-CLS-010, TST-ACC-CLS-017, TST-ACC-CLS-018, TST-ACC-CLS-021, TST-ACC-CLS-023, TST-ACC-CLS-029

KindCapabilityProduct areaAccountingModuleMonth-End ClosingRevision1

Read atservices-accounting f47cb263react-console baf6dae3

Complete a guarded month-end close ​

Purpose ​

A controller submits one close request whose durable execution validates the books and records the result.

How It Works ​

The controller opens the close dialog and reviews a fresh evaluation. They acknowledge the displayed warning outcomes and confirm the month by typing its label. The console submits a key that survives another attempt from the same dialog. The service creates the run and job together, then starts execution after saving them. A sequence problem or competing run returns a refusal. The job takes the month and evaluates readiness again. Required blocked, pending or error results release the month and identify the failure. Warnings alone allow execution to continue. Due revenue is recognized before finalization records the close and requests aging. Future-year generation follows that successful finalization. A failure can retain the period for recovery, depending on its step and committed revenue work. The product should enforce requester identity on repeated keys, as the recorded ruling requires.

Relationships ​

  • Authorization establishes the permitted sequence at submission.
  • Readiness supplies the execution re-check.
  • Revenue, year completion and recovery explain the individual execution outcomes.
  • Run tracking and the close record expose progress and retained evidence.

The Formal Contract

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

Outcomes
Repeated requests resolve to the original run when their command content matches.Required blockers discovered during execution leave the month open.Completed closes retain the requester and the evidence evaluated by the run.
Surfaces
consoleapijob
Preconditions
The selected period is open and next in the closing sequence.
Postconditions
The run completes with retained evidence, releases the period after refusal, or retains it for recovery after failure.
Constraints
The request returns a successful response containing its run; asynchronous acceptance status needs shared dispatcher support.
Intent sources
services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a row 74 (class A: close runs as a job with six steps, one active run per period)services-accounting:docs/milestones/ACCT-M4-contracts-and-events-for-commerce.md#Rulings recorded during the milestone

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-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-DAT-001 TC-LOG-001 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

KeyChecked atScope
accounting.fiscal-periods.closeapitenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
A close request requires a trimmed key of one to 255 characters and accepts an optional note up to two thousand characters and at most fifty warning acknowledgements; invalid or additional fields are refused.
proved by ATS-ACC-CLS-008-01, ATS-ACC-CLS-008-10, TST-ACC-CLS-005, TST-ACC-CLS-017
validationapitest
services-accounting:modules/fiscal-close/tests/e2e/fiscal-close-runs.e2e.spec.js#refuses a close without an idempotency key with 400
02must prove
Confirmed
The close permission is required to submit a close request.
origin: services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a row 73 (class A: authorised)
proved by ATS-ACC-CLS-008-01, TST-ACC-CLS-017
permissionapitest
services-accounting:modules/fiscal-close/tests/e2e/fiscal-close-runs.e2e.spec.js#refuses a principal without accounting.fiscal-periods.close with 403
03must prove
Confirmed
Repeating a key with the same command returns its run without another job, while a changed period, note or acknowledgement set is refused.
proved by ATS-ACC-CLS-008-02, TST-ACC-CLS-017, TST-ACC-CLS-018, TST-ACC-CLS-021, TST-ACC-CLS-029
policyservice, databasetest
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#refuses the same key with another body as idempotency-key-reused (409)
04must prove
Confirmed
The product should refuse another person’s command under an idempotency key already used by a requester.
✗ A colleague’s matching command currently receives the original requester’s run.
origin: services-accounting:docs/milestones/ACCT-M4-contracts-and-events-for-commerce.md#Rulings recorded during the milestone
proved by ATS-ACC-CLS-008-03
policydocumented
services-accounting:docs/milestones/ACCT-M4-contracts-and-events-for-commerce.md#Rulings recorded during the milestone
05must prove
Confirmed
A period accepts no competing run while one is queued or running, or while a failed run retains it in closing or reopening state.
origin: services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a row 74 (class A: one active run per period)
proved by ATS-ACC-CLS-008-02, ATS-ACC-CLS-008-09, TST-ACC-CLS-017, TST-ACC-CLS-018, TST-ACC-CLS-021, TST-ACC-CLS-029
invariantservice, databasetest
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#refuses another key while the first run holds the period, as period-run-active
06must prove
Confirmed
The request rejects an unavailable period or invalid sequence immediately, but accepts incomplete readiness for the job to assess.
proved by ATS-ACC-CLS-008-04, TST-ACC-CLS-004, TST-ACC-CLS-021
validationservicetest
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#ends the run failed at revalidate, not retryable
07must prove
Confirmed
The final period of a fiscal year creates a year-close run; other periods create period-close runs.
proved by ATS-ACC-CLS-008-05, TST-ACC-CLS-017, TST-ACC-CLS-021
policyservicetest
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#runs it as a year close, succeeded
08must prove
Confirmed
A close job locks, revalidates, recognizes revenue, skips cost of goods sold, finalizes and rolls years forward, starting after the request transaction commits.
origin: services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a row 74 (class A: close runs as a job with six steps)
proved by ATS-ACC-CLS-008-05, ATS-ACC-CLS-008-09, TST-ACC-CLS-017, TST-ACC-CLS-021
lifecycleservicetest
services-accounting:modules/fiscal-close/tests/e2e/fiscal-close-runs.e2e.spec.js#reads the run succeeded with its six steps
09must prove
Confirmed
Steps through finalization lock the period and reuse committed results on replay; roll-forward executes separately after closure.
origin: fiscal-close design L9 (Rhythm 1.0 CLOSE-9 fixed)
proved by ATS-ACC-CLS-008-06, ATS-ACC-CLS-008-09, TST-ACC-CLS-023
invariantservice, databaseobserved
services-accounting:modules/fiscal-close/services/jobs/fiscal-close-job-tasks.ts:rollForward
10must prove
Confirmed
Revalidation stores readiness and refuses required blocked, pending or error checks, releasing the month and failing the run without retry.
origin: services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a row 74 (class A; plan approved 2026-10-21)
proved by ATS-ACC-CLS-006-08, ATS-ACC-CLS-008-04, TST-ACC-CLS-004, TST-ACC-CLS-010, TST-ACC-CLS-021
policyservicetest
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#returns the period to open with no run holding it
11must prove
Confirmed
Unacknowledged warning outcomes do not stop execution and are recorded in a run event.
proved by ATS-ACC-CLS-008-07
policyserviceobserved
services-accounting:modules/fiscal-close/services/jobs/fiscal-close-job-tasks.ts:revalidate
12must prove
Confirmed
The console reviews warning outcomes and requires their acknowledgement before asking for the exact month label as confirmation.
proved by ATS-ACC-CLS-008-08, TST-ACC-CLS-001
policyconsoleobserved
react-console:components/accounting/close/close-dialog.tsx:CloseDialog
13must prove
Confirmed
Finalization atomically records the closed period, requester and close time, close snapshot, aging request and successful run, with the year following its final month.
origin: services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a row 74 (class A; plan approved 2026-10-21)
proved by ATS-ACC-CLS-008-05, ATS-ACC-CLS-008-09, TST-ACC-CLS-017, TST-ACC-CLS-021
lifecycleservice, databasetest
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#closes the period, by the requester, naming the run
14
Confirmed
Job authorization uses the system caller’s grants; the requester’s close grant is checked at submission.
permissionservicedocumented
services-accounting:docs/migrations/fiscal-close/README.md#Decisions and departures from the brief

Scenarios

IdGivenWhenThenProvenance
01September is clean and August is closed.The controller confirms September in the console with no warnings.Six steps settle, the empty recognition and cost steps are skipped, and the completed month has a close record.test
react-console:acceptance/accounting/playwright/journeys/reconciliation-close/ACT-ACC-0613.spec.ts#ACT-ACC-0613
02September has an unposted batch and a close request is submitted directly.The job evaluates readiness.Revalidation fails, returns September to open and identifies the batch blocker.test
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#names the blocking check in the run’s failure
03A command has a saved run and an unchanged request body.The same keyed command is submitted again.The response returns that run without another job.test
services-accounting:modules/fiscal-close/tests/integration/services/jobs/close-job.integration.spec.js#answers the same run for the same key, created once

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software