--- id: WF-ACC-CLS-005 title: Evaluate a month's close readiness trigger: >- A workspace, year review or confirmation dialog reads readiness, or execution revalidates its month. product_area: accounting module: close revision: 1 status: draft design_intent: confirmed origin: >- services-accounting:docs/milestones/plans/ACCT-M4-plan.md#4a row 73 (class A; plan approved 2026-10-21, D12); docs/fiscal-close/README.md#8 R5 (decided by Andrew 2026-10-16) implementation_evidence: observed inference: [] source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f implements: - CAP-ACC-CLS-004 - CAP-ACC-CLS-005 - CAP-ACC-CLS-006 - CAP-ACC-CLS-007 - CAP-ACC-CLS-010 crosses: - SVC-ACC-CLS-fiscal-close idempotency: >- Reading again calculates current readiness without persisting a standalone evaluation; returned values can change as the books change. concurrency: >- All checks share a read-only standalone transaction or the close’s writable transaction. The close locks its month, but no explicit isolation level freezes all readiness inputs, and other records can change during evaluation. hops: - 'n': 1 actor_or_service: Readiness route (reconciliation function) action: >- Require read access and validate year, month and scope, carrying the evaluated close grant into the execution context. anchor: >- services-accounting:modules/fiscal-close/aws/api/fiscal-close.routes.ts:fiscalCloseRoutes seam: sync on_failure: >- Request validation, authorization or missing-subject errors return to the caller. left_inconsistent: A rejected read changes no record. observer: The client receives the error response. provenance: test source: >- services-accounting:modules/fiscal-close/tests/e2e/fiscal-close-readiness.e2e.spec.js#refuses a period number out of range with 400 - 'n': 2 actor_or_service: Readiness engine action: >- Join the close transaction or open a read-only one, load calendar and policy, share payment assessments and recognition reads, and resolve merchant labels for the response. anchor: >- services-accounting:modules/fiscal-close/services/readiness/evaluate-readiness.ts:evaluateReadiness seam: sync on_failure: >- A missing subject fails the request; assessment failure becomes unavailable payment evidence. left_inconsistent: >- Standalone evaluation has no write effects; joined job evaluation is writable. observer: The returned checks and section report unavailable evidence. provenance: test source: >- services-accounting:modules/fiscal-close/tests/unit/readiness/reconciliation-checks.spec.js#is unavailable, not ready and empty when the assessment could not run - 'n': 3 actor_or_service: Readiness evaluators (one savepoint each) action: >- Run the selected evaluators in registry order, loading each under a savepoint and bounding returned supporting items. anchor: >- services-accounting:modules/fiscal-close/services/readiness/registry.ts:READINESS_EVALUATORS seam: sync on_failure: >- Rollback an unsuccessful load to its savepoint and return an error check with its applicable requirement. left_inconsistent: A failed evaluator leaves the transaction usable for later checks. observer: The checklist retains an explicit error outcome. provenance: test source: >- services-accounting:modules/fiscal-close/tests/integration/services/persistence/readiness-transactions.integration.spec.js#rolls an evaluator’s failure back to its savepoint and keeps the transaction usable - 'n': 4 actor_or_service: Readiness engine action: >- Calculate verdict and counts, assemble payment context and closing effects, and include evaluation time and caller. anchor: >- services-accounting:modules/fiscal-close/services/readiness/readiness-verdict.ts:overallOf seam: sync on_failure: An unexpected assembly error fails the read. left_inconsistent: The evaluation does not independently persist its response. observer: The caller receives the assembled review. provenance: test source: >- services-accounting:modules/fiscal-close/tests/unit/readiness/readiness-verdict.spec.js#is ready with warnings for an advisory check blocked, which never blocks - 'n': 5 actor_or_service: Console action: >- Render readiness and payment context, with person names resolved by the HTTP adapter through Platform. anchor: >- react-console:components/accounting/close/close-workspace.tsx:CloseWorkspace seam: sync on_failure: Load failures show the retry panel. left_inconsistent: Viewing the response makes no financial change. observer: The person reading the workspace sees the status and errors. provenance: observed source: >- react-console:components/accounting/close/close-workspace.tsx:CloseWorkspace branches: - Year scope adds three checks even when requested before the final month. - >- The current authorization check uses the reader’s close grant; the job evaluates with system authority. evidence: - >- services-accounting at f47cb263: modules/fiscal-close/services/readiness/*.ts; services/persistence/readiness-transactions.ts; modules/reconciliation/services/close-readiness/assess-period.ts:assessReconciliationReadiness. - >- react-console at baf6dae3: components/accounting/close/close-workspace.tsx, readiness-summary.tsx, readiness-checklist.tsx, check-detail-drawer.tsx; lib/accounting/close/checks.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-DAT-001, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005] --- # Evaluate a month's close readiness ## What It Does Readiness collects the month’s outstanding work, payment assessment and closing effects into one review. A standalone read is read-only. The close’s own revalidation runs the same evaluator within the transaction holding the month. ## The Flow ```mermaid sequenceDiagram participant Caller participant Engine as Readiness evaluator participant Payments as Reconciliation participant Checks Caller->>Engine: evaluate month and scope Engine->>Payments: read shared assessment loop ordered checks Engine->>Checks: load in savepoint and apply rule Checks-->>Engine: result or error check end Engine-->>Caller: verdict, context and effects ``` ## When Something Fails Each evaluator failure becomes an error check after rollback to its savepoint; the other checks continue. Required errors block the verdict. A failed payment assessment marks its checks as errors and its section unavailable. Shared transactions do not establish one immutable reading of every input, even under the target month’s lock. ## Open Design Questions Product must decide whether viewer authority belongs in readiness. Fiscal-year scope before the last month remains accepted. Checklist filtering and warning acknowledgements need to agree with the service classification.