@tailor-platform/erp-kit 0.6.0 → 0.8.0

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

@@ -0,0 +1,68 @@
+# ProcessManufacturingHandoff
+
+## Overview
+
+processManufacturingHandoff receives cost settlement events from the manufacturing module and creates corresponding Miscellaneous-type journal entries in the general ledger. The entry debits finished goods and variance accounts (material price variance, labor efficiency variance, overhead variance) and credits the WIP (work-in-progress) account. The command enforces idempotency and returns a ManufacturingCostSettlementAcknowledgment upon successful posting.
+
+## Business Rules
+
+- Receives a handoff event containing cost settlement data with WIP, finished goods, and variance account references
+- Creates a journal entry classified as Miscellaneous journal type
+- Debits finished goods account and applicable variance accounts (material price, labor efficiency, overhead)
+- Credits the WIP account
+- Variance entries are separately recorded for each applicable variance type
+- The journal entry must be balanced (total debits equal total credits in functional currency)
+- The journal entry carries a source document reference linking to the originating manufacturing settlement
+- Idempotent processing: duplicate events with the same source document reference return the original acknowledgment without re-posting
+- Validates that the target accounting period is in OPEN or FUTURE_ENTERABLE status
+- Validates that all referenced GL accounts are active in the Chart of Accounts
+- Handles deprecated GL accounts with successor mappings by redirecting to the successor
+- Supports multi-currency: foreign currency amounts are converted to base currency using the provided exchange rate
+- Rejects events with zero or negative amounts
+- Events are scoped to a company
+- Returns a ManufacturingCostSettlementAcknowledgment with journal entry ID and settlement reference
+- Emits an audit event recording the source module, document reference, and journal entry created
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive manufacturing handoff event] --> B{Idempotency check: already posted?}
+    B -->|Yes| C[Return existing acknowledgment]
+    B -->|No| D{Accounting period OPEN or FUTURE_ENTERABLE?}
+    D -->|No| E[Return error: invalid period status]
+    D -->|Yes| F{GL accounts valid and active?}
+    F -->|No| G[Return error: account validation failed]
+    F -->|Yes| H[Create entry: debit finished goods + variances, credit WIP]
+    H --> I[Post journal entry]
+    I --> J[Emit audit event]
+    J --> K[Return ManufacturingCostSettlementAcknowledgment]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that WIP, finished goods, and variance GL accounts are active
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates currency for multi-currency transactions
+
+## Error Scenarios
+
+- **INVALID_PERIOD_STATUS**: Target accounting period is not in OPEN or FUTURE_ENTERABLE status
+- **ACCOUNT_NOT_FOUND**: Referenced GL account does not exist
+- **ACCOUNT_NOT_ACTIVE**: Referenced GL account is not in active status
+- **INVALID_AMOUNT**: Handoff event contains zero or negative amounts
+- **COMPANY_MISMATCH**: Handoff event company does not match the GL account company scope
+
+## Test Cases
+
+- returns existing entry for idempotent duplicate
+- returns error when amount is zero or negative
+- returns error when amount is negative
+- returns error when period is not OPEN or FUTURE_ENTERABLE
+- returns error when period is CLOSED
+- returns error when company does not match period company
+- returns error when debit account is not found
+- returns error when credit account is not found
+- returns error when debit account is not active
+- returns error when credit account is not active
+- creates journal entry with correct type and amounts
+- handles multi-currency with exchange rate

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

@@ -0,0 +1,68 @@
+# ProcessPurchaseHandoff
+
+## Overview
+
+processPurchaseHandoff receives a purchase bill handoff event from the purchase module and creates a corresponding Purchase-type journal entry in the general ledger. The entry debits the expense or asset account and credits the accounts payable account, reflecting the payable recognition for a validated purchase bill. The command enforces idempotency via source document reference to prevent duplicate postings from retry scenarios. Upon successful posting, it returns a PurchaseBillPostingAcknowledgment to the purchase module.
+
+## Business Rules
+
+- Receives a handoff event containing the purchase bill amount, expense/asset account reference, and accounts payable account reference
+- Creates a journal entry classified as Purchase journal type
+- Debits the expense or asset account and credits the accounts payable account
+- The journal entry must be balanced (total debits equal total credits in functional currency)
+- The journal entry carries a source document reference linking to the originating purchase bill
+- Idempotent processing: duplicate events with the same source document reference return the original acknowledgment without re-posting
+- Validates that the target accounting period is in OPEN or FUTURE_ENTERABLE status
+- Validates that all referenced GL accounts are active in the Chart of Accounts
+- Handles deprecated GL accounts with successor mappings by redirecting to the successor
+- Supports multi-currency: foreign currency amounts are converted to base currency using the provided exchange rate
+- Rejects events with zero or negative amounts
+- Events are scoped to a company; events from one company cannot post to another company's GL
+- Returns a PurchaseBillPostingAcknowledgment with the generated journal entry ID and posting timestamp
+- Emits an audit event recording the source module, document reference, and journal entry created
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive purchase handoff event] --> B{Idempotency check: already posted?}
+    B -->|Yes| C[Return existing acknowledgment]
+    B -->|No| D{Accounting period OPEN or FUTURE_ENTERABLE?}
+    D -->|No| E[Return error: invalid period status]
+    D -->|Yes| F{GL accounts valid and active?}
+    F -->|No| G[Return error: account validation failed]
+    F -->|Yes| H{Amounts valid and positive?}
+    H -->|No| I[Return error: invalid amounts]
+    H -->|Yes| J[Create Purchase journal entry with debit expense/asset, credit AP]
+    J --> K[Post journal entry]
+    K --> L[Emit audit event]
+    L --> M[Return PurchaseBillPostingAcknowledgment]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that expense/asset and AP GL accounts are active
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates currency for multi-currency transactions
+
+## Error Scenarios
+
+- **INVALID_PERIOD_STATUS**: Target accounting period is not in OPEN or FUTURE_ENTERABLE status
+- **ACCOUNT_NOT_FOUND**: Referenced GL account does not exist
+- **ACCOUNT_NOT_ACTIVE**: Referenced GL account is not in active status
+- **INVALID_AMOUNT**: Handoff event contains zero or negative amounts
+- **COMPANY_MISMATCH**: Handoff event company does not match the GL account company scope
+
+## Test Cases
+
+- returns existing entry for idempotent duplicate
+- returns error when amount is zero or negative
+- returns error when amount is negative
+- returns error when period is not OPEN or FUTURE_ENTERABLE
+- returns error when period is CLOSED
+- returns error when company does not match period company
+- returns error when debit account does not exist
+- returns error when credit account does not exist
+- returns error when debit account is not active
+- returns error when credit account is not active
+- creates journal entry with correct type and amounts
+- handles multi-currency with exchange rate

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

@@ -0,0 +1,71 @@
+# ProcessSalesHandoff
+
+## Overview
+
+processSalesHandoff receives a sales invoice or credit note handoff event from the sales module and creates a corresponding Sales-type journal entry in the general ledger. For invoices, the entry debits accounts receivable and credits the revenue account. For credit notes, the entry reverses these (debit revenue, credit accounts receivable). The command enforces idempotency via source document reference and returns an acknowledgment upon successful posting.
+
+## Business Rules
+
+- Receives a handoff event containing the sales invoice or credit note data, accounts receivable reference, and revenue account reference
+- Creates a journal entry classified as Sales journal type
+- For sales invoices: debits accounts receivable and credits the revenue account
+- For credit notes: creates a reversing entry with debit to revenue and credit to accounts receivable
+- The journal entry must be balanced (total debits equal total credits in functional currency)
+- The journal entry carries a source document reference linking to the originating sales invoice or credit note
+- Idempotent processing: duplicate events with the same source document reference return the original acknowledgment without re-posting
+- Validates that the target accounting period is in OPEN or FUTURE_ENTERABLE status
+- Validates that all referenced GL accounts are active in the Chart of Accounts
+- Handles deprecated GL accounts with successor mappings by redirecting to the successor
+- Supports multi-currency: foreign currency amounts are converted to base currency using the provided exchange rate
+- Rejects events with zero or negative amounts
+- Events are scoped to a company
+- Returns an acknowledgment with the generated journal entry ID and posting timestamp
+- Emits an audit event recording the source module, document reference, and journal entry created
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive sales handoff event] --> B{Idempotency check: already posted?}
+    B -->|Yes| C[Return existing acknowledgment]
+    B -->|No| D{Accounting period OPEN or FUTURE_ENTERABLE?}
+    D -->|No| E[Return error: invalid period status]
+    D -->|Yes| F{GL accounts valid and active?}
+    F -->|No| G[Return error: account validation failed]
+    F -->|Yes| H{Invoice or credit note?}
+    H -->|Invoice| I[Create entry: debit AR, credit revenue]
+    H -->|Credit note| J[Create entry: debit revenue, credit AR]
+    I --> K[Post journal entry]
+    J --> K
+    K --> L[Emit audit event]
+    L --> M[Return acknowledgment]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that AR and revenue GL accounts are active
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates currency for multi-currency transactions
+
+## Error Scenarios
+
+- **INVALID_PERIOD_STATUS**: Target accounting period is not in OPEN or FUTURE_ENTERABLE status
+- **ACCOUNT_NOT_FOUND**: Referenced GL account does not exist
+- **ACCOUNT_NOT_ACTIVE**: Referenced GL account is not in active status
+- **INVALID_AMOUNT**: Handoff event contains zero or negative amounts
+- **COMPANY_MISMATCH**: Handoff event company does not match the GL account company scope
+
+## Test Cases
+
+- returns existing entry for idempotent duplicate
+- returns error when amount is zero or negative
+- returns error when amount is negative
+- returns error when period is not OPEN or FUTURE_ENTERABLE
+- returns error when period is CLOSED
+- returns error when company does not match period company
+- returns error when debit account is not active
+- returns error when credit account is not active
+- returns error when debit account does not exist
+- returns error when credit account does not exist
+- creates journal entry with correct type and amounts
+- handles multi-currency with exchange rate
+- swaps debit and credit accounts for credit note document type

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

@@ -0,0 +1,60 @@
+# RegenerateFinancialStatement
+
+## Overview
+
+regenerateFinancialStatement replaces the content of an existing DRAFT financial statement with fresh data from the current trial balance. This allows controllers to re-run statement generation after posting correcting journal entries or adjusting entries without creating a new statement entity. Only DRAFT statements can be regenerated — FINALIZED statements are immutable.
+
+## Business Rules
+
+- Financial statement must exist and be identified by `id`
+- Financial statement must be in DRAFT status; FINALIZED statements cannot be regenerated
+- The referenced trial balance must still exist and be valid
+- The system re-fetches the trial balance data and re-maps accounts to statement sections
+- All existing line items are replaced with the regenerated output
+- The generation timestamp is updated to reflect the regeneration time
+- If comparative period data was included, it is also refreshed from the comparative trial balance
+- Regeneration follows the same validation rules as initial generation (balanced trial balance, valid account mappings)
+- Emits an audit event via the audit module recording the acting user, timestamp, and regeneration parameters
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive regenerate 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: statement is finalized]
+    D -->|Yes| F[Fetch current trial balance data]
+    F --> G[Load account group hierarchy from coa-management]
+    G --> H[Re-map accounts to statement sections by account type]
+    H --> I[Aggregate balances per account group]
+    I --> J{Comparative period included?}
+    J -->|Yes| K[Refresh comparative period data]
+    K --> L[Replace all line items with regenerated output]
+    J -->|No| L
+    L --> M[Update generation timestamp]
+    M --> N[Emit audit event]
+    N --> O[Return regenerated statement]
+```
+
+## External Dependencies
+
+- [coa-management::listAccountGroups](../../../coa-management/docs/queries/ListAccountGroups.md) - Retrieves account group hierarchy for structuring statement sections
+
+## Error Scenarios
+
+- **FINANCIAL_STATEMENT_NOT_FOUND**: No financial statement matches the given id
+- **STATEMENT_ALREADY_FINALIZED**: Financial statement is in FINALIZED status and cannot be regenerated
+- **TRIAL_BALANCE_NOT_FOUND**: The referenced trial balance no longer exists
+- **TRIAL_BALANCE_IMBALANCED**: The trial balance has a non-zero debit-credit discrepancy
+- **COMPARATIVE_TRIAL_BALANCE_NOT_FOUND**: Comparative period trial balance is unavailable when requested
+
+## Test Cases
+
+- returns error when financial statement does not exist
+- returns error when financial statement is already FINALIZED
+- returns error when trial balance is not found
+- returns error when trial balance is imbalanced
+- returns error when comparative trial balance is not found
+- regenerates statement with fresh data and updates generatedAt
+- emits audit event recording statement regeneration

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

@@ -0,0 +1,42 @@
+# RemoveJournalLine
+
+## Overview
+
+removeJournalLine removes an existing line item from a DRAFT journal entry. Lines can only be removed while the parent entry is in DRAFT status. Lines on posted or reversed entries are immutable and cannot be removed, as this would compromise the audit trail.
+
+## Business Rules
+
+- Journal line must exist and its parent journal entry must be in DRAFT status
+- Lines on POSTED or REVERSED entries cannot be removed
+- Removing a line does not automatically delete the parent entry even if no lines remain
+- Emits an audit event recording the line removal, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive remove journal line request] --> B{Journal line exists?}
+    B -->|No| C[Return error: journal line not found]
+    B -->|Yes| D{Parent entry status is DRAFT?}
+    D -->|No| E[Return error: cannot remove lines from non-draft entry]
+    D -->|Yes| F[Remove journal line]
+    F --> G[Emit audit event]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **JOURNAL_LINE_NOT_FOUND**: Referenced journal line does not exist
+- **INVALID_STATUS_FOR_LINE_REMOVE**: Parent journal entry is not in DRAFT status
+
+## Test Cases
+
+- returns error when journal line does not exist
+- returns error when parent journal entry is in POSTED status
+- returns error when parent journal entry is in REVERSED status
+- removes journal line from DRAFT entry
+- emits audit event recording line removal and acting user

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

@@ -0,0 +1,45 @@
+# ReopenPeriod
+
+## Overview
+
+reopenPeriod transitions an accounting period from CLOSED back to OPEN status, allowing journal entry postings to resume. This supports scenarios where late-arriving transactions or corrections need to be recorded after initial close. The reopen operation emits an audit event for compliance tracking, as reopening a closed period is a sensitive action that auditors monitor.
+
+## Business Rules
+
+- Period must exist and be in CLOSED status
+- Only CLOSED periods can be reopened; PERMANENTLY_CLOSED periods cannot be reopened
+- After transition, the period resumes accepting journal entry postings
+- Reopening a period emits an audit event recording the status transition, acting user, and timestamp
+- The audit event is critical for compliance as reopening is a monitored action
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reopenPeriod request] --> B{Period exists?}
+    B -->|No| C[Return error: period not found]
+    B -->|Yes| D{Period status is CLOSED?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Transition period to OPEN]
+    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 CLOSED status; only CLOSED periods can be reopened
+
+## 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 OPEN status
+- returns error when period is in FUTURE_ENTERABLE status
+- returns error when period is in PERMANENTLY_CLOSED status
+- transitions CLOSED period back to OPEN
+- emits audit event recording status transition from CLOSED to OPEN and acting user

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

@@ -0,0 +1,62 @@
+# ReverseJournalEntry
+
+## Overview
+
+reverseJournalEntry creates a mirror journal entry with all debit and credit amounts inverted from the original posted entry, and automatically posts the reversal entry. The original entry transitions from POSTED to REVERSED status. This is the only way to correct a posted journal entry, as posted entries cannot be modified or deleted. The reversal entry must target a period that is in OPEN or FUTURE_ENTERABLE status.
+
+## Business Rules
+
+- Original journal entry must exist and be in POSTED status
+- DRAFT entries cannot be reversed (they should be deleted instead)
+- Already REVERSED entries cannot be reversed again
+- A new mirror journal entry is created with all debit amounts swapped to credits and vice versa
+- The reversal entry references the original entry
+- The reversal entry is automatically posted upon creation
+- The original entry status transitions from POSTED to REVERSED
+- The reversal entry must target an accounting period in OPEN or FUTURE_ENTERABLE status
+- Multi-currency lines are reversed with the same currency and exchange rate as the original
+- Emits an audit event recording the status transition from POSTED to REVERSED, the reversal entry reference, and the acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reverse journal entry request] --> B{Original entry exists?}
+    B -->|No| C[Return error: journal entry not found]
+    B -->|Yes| D{Original entry status is POSTED?}
+    D -->|No| E[Return error: invalid status for reversal]
+    D -->|Yes| F{Reversal period OPEN or FUTURE_ENTERABLE?}
+    F -->|No| G[Return error: invalid period status]
+    F -->|Yes| H[Create mirror entry with inverted debits/credits]
+    H --> I[Auto-post reversal entry]
+    I --> J[Transition original entry to REVERSED]
+    J --> K[Emit audit event]
+    K --> L[Return reversal entry]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
+- **INVALID_STATUS_FOR_REVERSAL**: Journal entry is not in POSTED status; only POSTED entries can be reversed
+- **ALREADY_REVERSED**: Journal entry has already been reversed
+- **INVALID_PERIOD_STATUS**: The reversal target period is not in OPEN or FUTURE_ENTERABLE status
+
+## Test Cases
+
+- returns error when journal entry does not exist
+- returns error when journal entry is in DRAFT status
+- returns error when journal entry is already REVERSED
+- returns error when reversal period is in NEVER_OPENED status
+- returns error when reversal period is in CLOSED status
+- returns error when reversal period is in PERMANENTLY_CLOSED status
+- creates mirror entry with all debit/credit amounts inverted
+- reversal entry references the original entry
+- reversal entry is automatically posted
+- original entry transitions from POSTED to REVERSED
+- reversal entry targets the specified accounting period
+- multi-currency lines are reversed with same currency and exchange rate
+- emits audit event recording status transition, reversal entry reference, and acting user

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

@@ -0,0 +1,49 @@
+# RevertSoftLock
+
+## Overview
+
+revertSoftLock transitions a PeriodClose from SOFT_LOCKED back to IN_PROGRESS status, allowing the close workflow to be revisited. This is used when errors are discovered after the period was soft-locked but before permanent close. After reverting, the accounting team can post corrections and re-run the close checklist steps. This operation is only permitted before permanent close.
+
+## Business Rules
+
+- PeriodClose record must exist and be in SOFT_LOCKED status
+- Only SOFT_LOCKED records can be reverted
+- Reverting a permanently closed period is not permitted
+- After revert, the PeriodClose returns to IN_PROGRESS status, allowing the full checklist to be re-executed
+- Updates completionPercentage to reflect the rollback
+- Records the userId of the operator who reverted the soft lock
+- Emits an audit event recording the acting user, timestamp, and status transition from SOFT_LOCKED to IN_PROGRESS
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive revert soft 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 IN_PROGRESS]
+    F --> G[Update completionPercentage]
+    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 SOFT_LOCKED status; only SOFT_LOCKED can be reverted to IN_PROGRESS
+- **PERIOD_PERMANENTLY_CLOSED**: Cannot revert a period close that has already been permanently closed
+
+## 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 in UNDER_REVIEW status
+- returns error when PeriodClose is PERMANENTLY_CLOSED
+- transitions SOFT_LOCKED period close to IN_PROGRESS
+- emits audit event recording status transition and acting user

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

@@ -0,0 +1,60 @@
+# UpdateFiscalYear
+
+## Overview
+
+updateFiscalYear modifies mutable fields of an existing fiscal year. The fiscal year name can always be updated. Start and end dates can be updated only if no accounting periods have been created for the fiscal year; once periods exist, dates become immutable to prevent date boundary changes that would invalidate existing period definitions.
+
+## Business Rules
+
+- Fiscal year must exist and be identified by `id`
+- The `yearName` field can be updated at any time
+- yearName is required and must be non-empty
+- Start date and end date can be updated only if no accounting periods exist for the fiscal year
+- Start date and end date are immutable once accounting periods have been created
+- If dates are updated, start date must be strictly before end date
+- If dates are updated, the new date range must not overlap with any other fiscal year for the same company
+- Emits an audit event via the audit module recording the acting user, timestamp, and changed fields
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update fiscal year request] --> B{Fiscal year exists?}
+    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{Date changes requested?}
+    F -->|Yes| G{Accounting periods exist?}
+    G -->|Yes| H[Return error: dates immutable]
+    G -->|No| I{Start date before end date?}
+    I -->|No| J[Return error: invalid date range]
+    I -->|Yes| K{Overlaps with existing fiscal year?}
+    K -->|Yes| L[Return error: overlapping fiscal year]
+    K -->|No| M[Update fiscal year record]
+    F -->|No| M
+    M --> N[Emit audit event]
+    N --> O[Return updated fiscal year]
+```
+
+## External Dependencies
+
+- None (same-module read for fiscal year lookup)
+
+## Error Scenarios
+
+- **FISCAL_YEAR_NOT_FOUND**: No fiscal year matches the given id
+- **NAME_REQUIRED**: Fiscal year name is empty or not provided
+- **DATES_IMMUTABLE**: Attempting to change start/end dates after accounting periods exist
+- **INVALID_DATE_RANGE**: Start date is not strictly before end date
+- **OVERLAPPING_FISCAL_YEAR**: The updated date range overlaps with an existing fiscal year for the same company
+
+## Test Cases
+
+- returns error when fiscal year does not exist
+- returns error when name is empty
+- returns error when attempting to change dates after accounting periods exist
+- returns error when updated start date is not before end date
+- returns error when updated date range overlaps with another fiscal year
+- updates fiscal year name successfully
+- updates fiscal year dates when no accounting periods exist
+- emits audit event recording acting user, timestamp, and changed fields

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

@@ -0,0 +1,47 @@
+# UpdateJournalEntry
+
+## Overview
+
+updateJournalEntry modifies the header fields of an existing journal entry that is in DRAFT status. Updatable fields include description, source document reference, entry date, and reference number. Posted and reversed entries are immutable and cannot be updated. This command does not affect journal lines, which are managed via addJournalLine, updateJournalLine, and removeJournalLine.
+
+## Business Rules
+
+- Journal entry must exist and be in DRAFT status
+- Only DRAFT entries can be updated; POSTED and REVERSED entries are immutable
+- Entry date can be updated while in DRAFT status
+- Description and source document reference can be updated while in DRAFT status
+- Emits an audit event recording previous and new field values, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update 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 modify non-draft entry]
+    D -->|Yes| F[Update header fields]
+    F --> G[Emit audit event]
+    G --> H[Return updated journal entry]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
+- **INVALID_STATUS_FOR_UPDATE**: Journal entry is not in DRAFT status; POSTED and REVERSED entries cannot be modified
+
+## 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
+- updates description on a DRAFT journal entry
+- updates source document reference on a DRAFT journal entry
+- updates entry date on a DRAFT journal entry
+- updates reference number on a DRAFT journal entry with uniqueness check
+- returns error when updated reference number already exists
+- emits audit event recording previous and new field values and acting user

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

@@ -0,0 +1,61 @@
+# UpdateJournalLine
+
+## Overview
+
+updateJournalLine modifies an existing line item on a DRAFT journal entry. Updatable fields include the GL account reference, debit or credit amount, currency, exchange rate, and line-level description. Lines on posted or reversed entries are immutable and cannot be updated.
+
+## Business Rules
+
+- Journal line must exist and its parent journal entry must be in DRAFT status
+- Lines on POSTED or REVERSED entries cannot be updated
+- Updated account reference must be a valid GL account from coa-management
+- Updated debit/credit must follow the same rules as creation (one or the other, positive values)
+- Multi-currency updates must include valid currency and exchange rate
+- Functional currency amount is recomputed when amount or exchange rate changes
+- Emits an audit event recording previous and new field values, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update journal line request] --> B{Journal line exists?}
+    B -->|No| C[Return error: journal line not found]
+    B -->|Yes| D{Parent entry status is DRAFT?}
+    D -->|No| E[Return error: cannot modify lines on non-draft entry]
+    D -->|Yes| F{Updated fields valid?}
+    F -->|No| G[Return error: validation failed]
+    F -->|Yes| H[Update journal line fields]
+    H --> I[Recompute functional currency amount if needed]
+    I --> J[Emit audit event]
+    J --> K[Return updated journal line]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that the updated GL account reference exists
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates that the updated currency exists and is active
+
+## Error Scenarios
+
+- **JOURNAL_LINE_NOT_FOUND**: Referenced journal line does not exist
+- **INVALID_STATUS_FOR_LINE_UPDATE**: Parent journal entry is not in DRAFT status
+- **ACCOUNT_NOT_FOUND**: Updated GL account reference does not exist
+- **INVALID_DEBIT_CREDIT**: Updated debit/credit values violate constraints (both specified, both zero, or negative)
+- **CURRENCY_NOT_FOUND**: Updated currency does not exist or is not active
+
+## Test Cases
+
+- returns error when journal line does not exist
+- returns error when parent journal entry is in POSTED status
+- returns error when parent journal entry is in REVERSED status
+- returns error when updated GL account does not exist
+- returns error when updated GL account is not active
+- returns error when updated debit/credit values are invalid
+- returns error when updated currency does not exist
+- updates GL account reference on a journal line
+- updates debit amount on a journal line
+- updates credit amount on a journal line
+- updates currency and exchange rate on a journal line
+- recomputes functional currency amount after update
+- updates line-level description
+- emits audit event recording previous and new field values and acting user