@tailor-platform/erp-kit 0.6.0 → 0.8.0

package/src/modules/finance-ledger/docs/commands/ApproveAndLockPeriod.md

@@ -0,0 +1,53 @@
+# ApproveAndLockPeriod
+
+## Overview
+
+approveAndLockPeriod transitions a PeriodClose from UNDER_REVIEW to SOFT_LOCKED status, indicating that the accounting team has approved the period's financial data. A soft-locked period prevents the accounting team from posting new journal entries while still allowing users with the advisor/auditor role to post final adjustments. This supports segregation of duties in the close workflow.
+
+## Business Rules
+
+- PeriodClose record must exist and be in UNDER_REVIEW status
+- Only UNDER_REVIEW records can transition to SOFT_LOCKED
+- Approval requires a user with the appropriate authorization role (e.g., controller or finance manager)
+- Soft-locking a period prevents the accounting team from posting new journal entries to that period
+- Soft-locked period still allows postings from users with the advisor/auditor role
+- Updates completionPercentage to reflect progress
+- Records the userId of the approver who locked the period
+- Emits an audit event recording the acting user, timestamp, approval details, and status transition
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive approve and lock request] --> B{PeriodClose record exists?}
+    B -->|No| C[Return error: period close not found]
+    B -->|Yes| D{PeriodClose in UNDER_REVIEW status?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F{User has authorization role?}
+    F -->|No| G[Return error: insufficient permissions]
+    F -->|Yes| H[Transition PeriodClose to SOFT_LOCKED]
+    H --> I[Block accounting team postings for the period]
+    I --> J[Update completionPercentage]
+    J --> K[Emit audit event]
+    K --> L[Return updated PeriodClose]
+```
+
+## External Dependencies
+
+- [user-management::listUserRolesByUser](../../../user-management/docs/queries/ListUserRolesByUser.md) - Validates that the acting user has the required authorization role (controller or finance manager)
+
+## Error Scenarios
+
+- **PERIOD_CLOSE_NOT_FOUND**: No PeriodClose record matches the given id
+- **INVALID_STATUS_TRANSITION**: PeriodClose is not in UNDER_REVIEW status; only UNDER_REVIEW can transition to SOFT_LOCKED
+- **INSUFFICIENT_PERMISSIONS**: Acting user does not have the required authorization role (controller or finance manager)
+
+## Test Cases
+
+- returns error when PeriodClose record does not exist
+- returns error when PeriodClose is in NOT_STARTED status
+- returns error when PeriodClose is in IN_PROGRESS status
+- returns error when PeriodClose is already SOFT_LOCKED
+- returns error when user lacks required permissions
+- transitions UNDER_REVIEW PeriodClose to SOFT_LOCKED with approvedByUserId and completionPercentage
+- emits audit event recording status transition from UNDER_REVIEW to SOFT_LOCKED

package/src/modules/finance-ledger/docs/commands/BeginClose.md

@@ -0,0 +1,47 @@
+# BeginClose
+
+## Overview
+
+beginClose transitions a PeriodClose record from NOT_STARTED to IN_PROGRESS status, indicating that the close checklist execution has begun. This is the first step after initiating the close and signals that the accounting team is actively working through the close workflow.
+
+## Business Rules
+
+- PeriodClose record must exist and be identified by the period close `id`
+- PeriodClose must be in NOT_STARTED status
+- Only NOT_STARTED records can transition to IN_PROGRESS
+- Records the userId of the operator who began the close
+- Updates completionPercentage to reflect progress
+- Emits an audit event via the audit module recording the acting user, timestamp, previous status (NOT_STARTED), and new status (IN_PROGRESS)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive begin close request] --> B{PeriodClose record exists?}
+    B -->|No| C[Return error: period close not found]
+    B -->|Yes| D{PeriodClose in NOT_STARTED status?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Transition PeriodClose to IN_PROGRESS]
+    F --> G[Record acting user]
+    G --> H[Emit audit event]
+    H --> I[Return updated PeriodClose]
+```
+
+## External Dependencies
+
+- None (same-module read for period close lookup)
+
+## Error Scenarios
+
+- **PERIOD_CLOSE_NOT_FOUND**: No PeriodClose record matches the given id
+- **INVALID_STATUS_TRANSITION**: PeriodClose is not in NOT_STARTED status; only NOT_STARTED can transition to IN_PROGRESS
+
+## Test Cases
+
+- returns error when PeriodClose record does not exist
+- returns error when PeriodClose is already IN_PROGRESS
+- returns error when PeriodClose is in SUBLEDGERS_VERIFIED status
+- returns error when PeriodClose is in PERMANENTLY_CLOSED status
+- transitions NOT_STARTED PeriodClose to IN_PROGRESS
+- records the acting user who began the close
+- emits audit event recording status transition from NOT_STARTED to IN_PROGRESS and acting user

package/src/modules/finance-ledger/docs/commands/ClosePeriod.md

@@ -0,0 +1,45 @@
+# ClosePeriod
+
+## Overview
+
+closePeriod transitions an accounting period from OPEN to CLOSED status. A closed period no longer accepts routine journal entry postings. The transition is reversible -- a closed period can be reopened if adjustments are needed before permanent close. This supports the month-end close workflow where periods are closed after reconciliation but may need to be reopened for late-arriving transactions.
+
+## Business Rules
+
+- Period must exist and be in OPEN status
+- Only OPEN periods can transition to CLOSED
+- After transition, journal entry postings to this period are rejected
+- The transition is reversible via reopenPeriod
+- Emits an audit event recording the status transition from OPEN to CLOSED, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive closePeriod request] --> B{Period exists?}
+    B -->|No| C[Return error: period not found]
+    B -->|Yes| D{Period status is OPEN?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Transition period to CLOSED]
+    F --> G[Emit audit event]
+    G --> H[Return updated period]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **INVALID_STATUS_TRANSITION**: Period is not in OPEN status; only OPEN periods can transition to CLOSED
+
+## Test Cases
+
+- returns error when accounting period does not exist
+- returns error when period is in NEVER_OPENED status
+- returns error when period is in FUTURE_ENTERABLE status
+- returns error when period is in CLOSED status
+- returns error when period is in PERMANENTLY_CLOSED status
+- transitions OPEN period to CLOSED
+- emits audit event recording status transition from OPEN to CLOSED and acting user

package/src/modules/finance-ledger/docs/commands/CreateAccountingPeriod.md

@@ -0,0 +1,69 @@
+# CreateAccountingPeriod
+
+## Overview
+
+createAccountingPeriod establishes a new accounting period in NEVER_OPENED status within a fiscal year. Each period carries a name, start date, end date, period type (e.g., monthly, quarterly, adjustment), and is linked to a fiscal year via `fiscalYearId`. Periods represent the discrete time segments within a fiscal year that control when journal entries can be posted. The system validates that the period does not overlap with existing periods and that there are no gaps in coverage within the fiscal year.
+
+## Business Rules
+
+- Period must reference a valid `fiscalYearId` belonging to the same company
+- Period name is required and must be non-empty
+- Start date and end date are required, with start date strictly before end date
+- Period type is required (e.g., monthly, quarterly, adjustment)
+- Periods within the same fiscal year must not have overlapping date ranges
+- Periods within the same fiscal year must cover the full fiscal year date range without gaps
+- Two periods in the same fiscal year cannot have identical start and end dates unless one is an adjustment period
+- Adjustment periods share the same end date as the final regular period but are typed as adjustment
+- Period is always created in NEVER_OPENED status
+- Period must reference a valid `companyId`; the period is scoped to the same company as its fiscal year
+- Emits an audit event via the audit module recording the acting user, timestamp, period details, and fiscal year reference
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create period request] --> B{Fiscal year exists and belongs to company?}
+    B -->|No| C[Return error: fiscal year not found]
+    B -->|Yes| D{Name non-empty?}
+    D -->|No| E[Return error: name required]
+    D -->|Yes| F{Start date before end date?}
+    F -->|No| G[Return error: invalid date range]
+    F -->|Yes| H{Overlaps with existing period in fiscal year?}
+    H -->|Yes| I[Return error: overlapping period]
+    H -->|No| J{Valid period type?}
+    J -->|No| K[Return error: invalid period type]
+    J -->|Yes| L[Create period in NEVER_OPENED status]
+    L --> M[Emit audit event]
+    M --> N[Return created period]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) - Validates that the referenced company exists and is ACTIVE
+
+## Error Scenarios
+
+- **FISCAL_YEAR_NOT_FOUND**: Referenced fiscal year does not exist or does not belong to the specified company
+- **NAME_REQUIRED**: Period name is empty or not provided
+- **INVALID_DATE_RANGE**: Start date is not strictly before end date
+- **OVERLAPPING_PERIOD**: The date range overlaps with an existing period within the same fiscal year
+- **INVALID_PERIOD_TYPE**: Period type is not a recognized value
+- **DUPLICATE_PERIOD_DATES**: Two periods have identical start and end dates and neither is an adjustment period
+
+## Test Cases
+
+- returns error when fiscal year does not exist
+- returns error when fiscal year belongs to a different company
+- returns error when name is empty
+- returns error when start date is not before end date
+- returns error when start date equals end date
+- returns error when period type is invalid
+- returns error when period overlaps with an existing period in the same fiscal year
+- returns error when two periods have identical dates and neither is adjustment type
+- creates period in NEVER_OPENED status with valid inputs
+- creates 12 monthly periods with correct date boundaries for a calendar fiscal year
+- creates 13 periods (12 operating + 1 adjustment) for a fiscal year
+- adjustment period shares the same end date as the final regular period
+- creates periods for a non-calendar fiscal year with correct boundaries
+- periods are scoped to a company; periods from different companies are isolated
+- emits audit event recording acting user, timestamp, and period details

package/src/modules/finance-ledger/docs/commands/CreateFiscalYear.md

@@ -0,0 +1,56 @@
+# CreateFiscalYear
+
+## Overview
+
+createFiscalYear establishes a new fiscal year record for a company. The fiscal year carries a name, start date, end date, and is scoped to a single company via `companyId`. Fiscal years serve as the top-level temporal grouping under which accounting periods are created. The system validates that the fiscal year does not overlap with any existing fiscal year for the same company.
+
+## Business Rules
+
+- Fiscal year requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Fiscal year name is required and must be non-empty
+- Start date and end date are required, with start date strictly before end date
+- Fiscal year date range must not overlap with any existing fiscal year for the same company
+- Supports non-calendar fiscal years (e.g., April-to-March, February-to-January)
+- Supports 4-4-5 week structures and 13-period fiscal calendars
+- Fiscal years are scoped to a company; records from different companies are isolated
+- Emits an audit event via the audit module recording the acting user, timestamp, company reference, and fiscal year details
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create fiscal year request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: company not found or inactive]
+    B -->|Yes| D{Name non-empty?}
+    D -->|No| E[Return error: name required]
+    D -->|Yes| F{Start date before end date?}
+    F -->|No| G[Return error: invalid date range]
+    F -->|Yes| H{Overlaps with existing fiscal year?}
+    H -->|Yes| I[Return error: overlapping fiscal year]
+    H -->|No| J[Create fiscal year record]
+    J --> K[Emit audit event]
+    K --> L[Return created fiscal year]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) - Validates that the referenced company exists and is ACTIVE
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **NAME_REQUIRED**: Fiscal year name is empty or not provided
+- **INVALID_DATE_RANGE**: Start date is not strictly before end date
+- **OVERLAPPING_FISCAL_YEAR**: The date range overlaps with an existing fiscal year for the same company
+
+## Test Cases
+
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when name is empty
+- returns error when start date is not before end date
+- returns error when fiscal year overlaps with an existing fiscal year for the same company
+- creates fiscal year with valid name, start date, and end date
+- creates non-calendar fiscal year (e.g., April-to-March) with correct date boundaries
+- fiscal years from different companies are isolated
+- emits audit event recording acting user, timestamp, company reference, and fiscal year details

package/src/modules/finance-ledger/docs/commands/CreateJournalEntry.md

@@ -0,0 +1,63 @@
+# CreateJournalEntry
+
+## Overview
+
+createJournalEntry establishes a new journal entry in DRAFT status within the general ledger. The journal entry header carries a company reference, accounting period reference, journal type (Sales, Purchase, Cash, Bank, Miscellaneous, Opening), reference number, entry date, optional description, and optional source document reference. Journal entries are the fundamental transactional unit of double-entry bookkeeping; lines are added separately via addJournalLine before the entry can be posted.
+
+## Business Rules
+
+- Journal entry is always created in DRAFT status
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a valid `accountingPeriodId` referencing an existing accounting period
+- Requires a valid journal type: Sales, Purchase, Cash, Bank, Miscellaneous, or Opening
+- Requires a reference number that is unique within the company scope
+- Requires a valid entry date
+- Description is optional and can be set on creation
+- Source document reference is optional and can be set on creation
+- Journal entries are scoped to a company; entries from different companies are fully isolated
+- Emits an audit event via the audit module recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create journal entry request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: company not found]
+    B -->|Yes| D{Accounting period exists?}
+    D -->|No| E[Return error: period not found]
+    D -->|Yes| F{Valid journal type?}
+    F -->|No| G[Return error: invalid journal type]
+    F -->|Yes| H{Reference number unique within company?}
+    H -->|No| I[Return error: duplicate reference number]
+    H -->|Yes| J{Valid entry date?}
+    J -->|No| K[Return error: invalid entry date]
+    J -->|Yes| L[Create journal entry in DRAFT status]
+    L --> M[Emit audit event]
+    M --> N[Return created journal entry]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) - Validates that the referenced company exists and is ACTIVE
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **INVALID_JOURNAL_TYPE**: Journal type is not one of the recognized values (Sales, Purchase, Cash, Bank, Miscellaneous, Opening)
+- **DUPLICATE_REFERENCE_NUMBER**: A journal entry with the same reference number already exists within the company
+- **INVALID_ENTRY_DATE**: Entry date is not a valid date
+
+## Test Cases
+
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when accounting period does not exist
+- returns error when journal type is invalid
+- returns error when reference number already exists within the company
+- returns error when entry date is invalid
+- creates journal entry in DRAFT status with required fields
+- creates journal entry with optional description
+- creates journal entry with optional source document reference
+- journal entries from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values

package/src/modules/finance-ledger/docs/commands/DeleteAccountingPeriod.md

@@ -0,0 +1,46 @@
+# DeleteAccountingPeriod
+
+## Overview
+
+deleteAccountingPeriod permanently removes an accounting period record. Deletion is only permitted when the period has no associated journal entries, regardless of their status (DRAFT, POSTED, or REVERSED). This prevents orphaned financial data and maintains referential integrity within the general ledger.
+
+## Business Rules
+
+- Accounting period must exist and be identified by `id`
+- Accounting period cannot be deleted if it has any associated journal entries regardless of status
+- Accounting period cannot be deleted if it has an active PeriodClose record
+- Deletion is a hard delete — the record is permanently removed
+- Emits an audit event via the audit module recording the acting user, timestamp, and deleted period details
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete accounting period request] --> B{Accounting period exists?}
+    B -->|No| C[Return error: period not found]
+    B -->|Yes| D{Journal entries exist for this period?}
+    D -->|Yes| E[Return error: has associated journal entries]
+    D -->|No| F{Active PeriodClose exists?}
+    F -->|Yes| G[Return error: has active close in progress]
+    F -->|No| H[Delete accounting period record]
+    H --> I[Emit audit event]
+    I --> J[Return success]
+```
+
+## External Dependencies
+
+- None (same-module read for period, journal entry, and period close lookup)
+
+## Error Scenarios
+
+- **ACCOUNTING_PERIOD_NOT_FOUND**: No accounting period matches the given id
+- **HAS_ASSOCIATED_JOURNAL_ENTRIES**: Accounting period has one or more journal entries and cannot be deleted
+- **HAS_ACTIVE_PERIOD_CLOSE**: Accounting period has an active period close record in progress
+
+## Test Cases
+
+- returns error when accounting period does not exist
+- returns error when accounting period has associated journal entries
+- returns error when accounting period has an active period close record
+- deletes accounting period with no associated journal entries or period close
+- emits audit event recording acting user, timestamp, and deleted period details

package/src/modules/finance-ledger/docs/commands/DeleteFiscalYear.md

@@ -0,0 +1,40 @@
+# DeleteFiscalYear
+
+## Overview
+
+deleteFiscalYear permanently removes a fiscal year record. Deletion is only permitted when the fiscal year has no associated accounting periods, ensuring that period data and any downstream journal entries are never orphaned.
+
+## Business Rules
+
+- Fiscal year must exist and be identified by `id`
+- Fiscal year cannot be deleted if it has any associated accounting periods
+- Deletion is a hard delete — the record is permanently removed
+- Emits an audit event via the audit module recording the acting user, timestamp, and deleted fiscal year details
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete fiscal year request] --> B{Fiscal year exists?}
+    B -->|No| C[Return error: fiscal year not found]
+    B -->|Yes| D{Accounting periods exist for this fiscal year?}
+    D -->|Yes| E[Return error: has associated periods]
+    D -->|No| F[Delete fiscal year record]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None (same-module read for fiscal year and period lookup)
+
+## Error Scenarios
+
+- **FISCAL_YEAR_NOT_FOUND**: No fiscal year matches the given id
+- **HAS_ASSOCIATED_PERIODS**: Fiscal year has one or more accounting periods and cannot be deleted
+
+## Test Cases
+
+- returns error when fiscal year does not exist
+- returns error when fiscal year has associated accounting periods
+- deletes fiscal year with no associated accounting periods

package/src/modules/finance-ledger/docs/commands/DeleteJournalEntry.md

@@ -0,0 +1,44 @@
+# DeleteJournalEntry
+
+## Overview
+
+deleteJournalEntry removes a journal entry and all its associated journal lines from the system. Only DRAFT entries can be deleted. Posted entries must be reversed rather than deleted to preserve the audit trail. Reversed entries also cannot be deleted. This ensures that all financial transactions that have affected the general ledger remain traceable.
+
+## Business Rules
+
+- Journal entry must exist and be in DRAFT status
+- Only DRAFT entries can be deleted; POSTED and REVERSED entries cannot be deleted
+- Deleting a DRAFT entry removes all associated journal lines
+- Posted entries must be reversed via reverseJournalEntry instead of deleted
+- Emits an audit event recording the deletion, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete journal entry request] --> B{Journal entry exists?}
+    B -->|No| C[Return error: journal entry not found]
+    B -->|Yes| D{Entry status is DRAFT?}
+    D -->|No| E[Return error: cannot delete non-draft entry]
+    D -->|Yes| F[Delete all associated journal lines]
+    F --> G[Delete journal entry]
+    G --> H[Emit audit event]
+    H --> I[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
+- **INVALID_STATUS_FOR_DELETE**: Journal entry is not in DRAFT status; POSTED and REVERSED entries cannot be deleted
+
+## Test Cases
+
+- returns error when journal entry does not exist
+- returns error when journal entry is in POSTED status
+- returns error when journal entry is in REVERSED status
+- deletes DRAFT journal entry and all associated journal lines
+- emits audit event recording the deletion and acting user

package/src/modules/finance-ledger/docs/commands/ExecuteYearEndClose.md

@@ -0,0 +1,81 @@
+# ExecuteYearEndClose
+
+## Overview
+
+executeYearEndClose runs the fiscal year-end close process on the final period of a fiscal year. It generates a closing journal entry that zeroes out all temporary accounts (REVENUE and EXPENSE types) and transfers the net income or net loss to the retained earnings account. It then generates opening balance entries for the first period of the new fiscal year, carrying forward all permanent account balances (ASSET, LIABILITY, EQUITY). This command can only be executed after the final period's standard close checklist has been completed.
+
+## Business Rules
+
+- Can only be initiated for the final period of a fiscal year
+- Initiating year-end close for a non-final period is rejected
+- Requires the final period's standard close checklist to be completed through the soft-lock or permanent close stage
+- Identifies all temporary accounts (REVENUE and EXPENSE types) with posted journal lines during the fiscal year
+- Calculates net income or net loss: total revenue minus total expenses
+- Looks up the retained earnings account from the CoA configuration (account with RETAINED_EARNINGS operational classification)
+- Fails if no account with RETAINED_EARNINGS operational classification exists in the active CoA
+- Generates a closing journal entry that debits all revenue accounts to zero and credits all expense accounts to zero
+- Posts the net difference (net income/loss) to the retained earnings account
+- The closing journal entry must be balanced (total debits equal total credits)
+- The closing journal entry is flagged with a distinct journal type (CLOSING)
+- The closing entry is posted to the final period of the fiscal year
+- Only accounts with posted journal lines during the fiscal year are included in the closing entry (zero-balance temporary accounts are excluded)
+- Generates opening balance entries for all permanent accounts (ASSET, LIABILITY, EQUITY types)
+- Opening balance entries carry the correct closing balance from each permanent account, including updated retained earnings
+- Opening balance entries are posted to the first period of the new fiscal year
+- Opening balance entries are flagged with a distinct journal type (OPENING)
+- The sum of all opening balance debits equals the sum of all opening balance credits
+- Opening balances are only generated if the new fiscal year's periods exist
+- Fails gracefully if the new fiscal year has not been defined
+- Year-end close cannot be run twice for the same fiscal year; duplicate attempts are rejected
+- After year-end close, the final period of the old fiscal year is permanently closed
+- Year-end close is scoped to a single company
+- Emits audit events recording each step: closing entry generation, retained earnings posting, opening balance generation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive execute year-end close request] --> B{Period is the final period of a fiscal year?}
+    B -->|No| C[Return error: not final period]
+    B -->|Yes| D{Standard close checklist completed?}
+    D -->|No| E[Return error: standard close not complete]
+    D -->|Yes| F{Already run for this fiscal year?}
+    F -->|Yes| G[Return error: duplicate year-end close]
+    F -->|No| H[Identify all REVENUE and EXPENSE accounts with activity]
+    H --> I[Calculate net income/loss]
+    I --> J{Retained earnings account configured in CoA?}
+    J -->|No| K[Return error: retained earnings account required]
+    J -->|Yes| L[Generate closing journal entry]
+    L --> M[Debit revenue accounts to zero, credit expense accounts to zero]
+    M --> N[Post net difference to retained earnings]
+    N --> O{New fiscal year periods exist?}
+    O -->|No| P[Return error: new fiscal year not defined]
+    O -->|Yes| Q[Generate opening balance entries for permanent accounts]
+    Q --> R[Post opening balances to first period of new fiscal year]
+    R --> S[Permanently close final period]
+    S --> T[Emit audit events]
+    T --> U[Return year-end close result]
+```
+
+## External Dependencies
+
+- [coa-management::getChartOfAccounts](../../../coa-management/docs/queries/GetChartOfAccounts.md) - Retrieves the active CoA, account types, and retained earnings account configuration
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Retrieves individual GL accounts for closing and opening entries
+
+## Error Scenarios
+
+- **NOT_FINAL_PERIOD**: The specified period is not the final period of its fiscal year
+- **STANDARD_CLOSE_NOT_COMPLETE**: The final period's standard close checklist has not been completed through soft-lock or permanent close
+- **DUPLICATE_YEAR_END_CLOSE**: Year-end close has already been executed for this fiscal year
+- **RETAINED_EARNINGS_ACCOUNT_NOT_FOUND**: No account with RETAINED_EARNINGS operational classification exists in the active CoA
+- **NEW_FISCAL_YEAR_NOT_DEFINED**: The new fiscal year has not been defined; opening balance entries cannot be generated
+
+## Test Cases
+
+- returns error when accounting period does not exist
+- returns error when period is not the final period of its fiscal year
+- returns error when standard close checklist is not complete
+- returns error when year-end close has already been executed
+- returns error when no retained earnings account exists
+- returns error when no new fiscal year is defined
+- successfully executes year-end close

package/src/modules/finance-ledger/docs/commands/FinalCloseAndLockPeriod.md

@@ -0,0 +1,49 @@
+# FinalCloseAndLockPeriod
+
+## Overview
+
+finalCloseAndLockPeriod transitions a PeriodClose from SOFT_LOCKED to PERMANENTLY_CLOSED status. This is the final step in the period-end close workflow. Once permanently closed, the accounting period becomes fully immutable — no further journal entries can be posted regardless of user role, and the period cannot be reopened. The underlying AccountingPeriod is also transitioned to PERMANENTLY_CLOSED status.
+
+## Business Rules
+
+- PeriodClose record must exist and be in SOFT_LOCKED status
+- Only SOFT_LOCKED records can transition to PERMANENTLY_CLOSED
+- Permanently closing a period makes it fully immutable; no further journal entries can be posted regardless of role
+- The underlying AccountingPeriod is transitioned to PERMANENTLY_CLOSED status
+- A permanently closed period cannot be reverted
+- Updates completionPercentage to 100%
+- Records the userId of the operator who finalized the close
+- Emits an audit event recording the acting user, timestamp, and irreversible status transition
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive final close and lock request] --> B{PeriodClose record exists?}
+    B -->|No| C[Return error: period close not found]
+    B -->|Yes| D{PeriodClose in SOFT_LOCKED status?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Transition PeriodClose to PERMANENTLY_CLOSED]
+    F --> G[Transition AccountingPeriod to PERMANENTLY_CLOSED]
+    G --> H[Set completionPercentage to 100%]
+    H --> I[Emit audit event]
+    I --> J[Return finalized PeriodClose]
+```
+
+## External Dependencies
+
+- None (same-module mutation for accounting period status transition)
+
+## Error Scenarios
+
+- **PERIOD_CLOSE_NOT_FOUND**: No PeriodClose record matches the given id
+- **INVALID_STATUS_TRANSITION**: PeriodClose is not in SOFT_LOCKED status; only SOFT_LOCKED can transition to PERMANENTLY_CLOSED
+
+## Test Cases
+
+- returns error when PeriodClose record does not exist
+- returns error when PeriodClose is in UNDER_REVIEW status
+- returns error when PeriodClose is in IN_PROGRESS status
+- transitions SOFT_LOCKED PeriodClose to PERMANENTLY_CLOSED with completionPercentage 100
+- also updates the associated AccountingPeriod to PERMANENTLY_CLOSED
+- emits audit event recording status transition from SOFT_LOCKED to PERMANENTLY_CLOSED

package/src/modules/finance-ledger/docs/commands/FinalizeFinancialStatement.md

@@ -0,0 +1,43 @@
+# FinalizeFinancialStatement
+
+## Overview
+
+finalizeFinancialStatement transitions a financial statement from DRAFT to FINALIZED status, making it immutable. Once finalized, the statement's line items, parameters, and output cannot be modified or regenerated. This ensures that published financial statements maintain their integrity for audit and regulatory purposes.
+
+## Business Rules
+
+- Financial statement must exist and be identified by `id`
+- Financial statement must be in DRAFT status
+- FINALIZED statements cannot be finalized again (no-op / invalid status transition)
+- Once finalized, the statement is immutable — line items, parameters, and output cannot be modified
+- A FINALIZED statement cannot be regenerated
+- Emits an audit event via the audit module recording the status transition from DRAFT to FINALIZED, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive finalize statement request] --> B{Financial statement exists?}
+    B -->|No| C[Return error: statement not found]
+    B -->|Yes| D{Statement in DRAFT status?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Transition statement to FINALIZED]
+    F --> G[Emit audit event]
+    G --> H[Return finalized statement]
+```
+
+## External Dependencies
+
+- None (same-module read for financial statement lookup)
+
+## Error Scenarios
+
+- **FINANCIAL_STATEMENT_NOT_FOUND**: No financial statement matches the given id
+- **INVALID_STATUS_TRANSITION**: Financial statement is not in DRAFT status; only DRAFT statements can be finalized. Also applies when attempting to finalize an already FINALIZED statement
+
+## Test Cases
+
+- returns error when financial statement does not exist
+- returns error when financial statement is already FINALIZED
+- transitions DRAFT statement to FINALIZED with finalizedAt set
+- emits audit event recording status transition from DRAFT to FINALIZED