@tailor-platform/erp-kit 0.5.1 → 0.7.0

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

@@ -0,0 +1,86 @@
+# GenerateFinancialStatement
+
+## Overview
+
+generateFinancialStatement creates a financial statement in DRAFT status from trial balance data. The statement can be a Balance Sheet, Profit & Loss, or Cash Flow Statement, scoped to a single company and structured according to the account group hierarchy from coa-management. Statement generation maps GL accounts to the appropriate report sections based on account type and aggregates balances per account group. A DRAFT statement can be regenerated with updated trial balance data before finalization.
+
+## Business Rules
+
+- Requires a valid `companyId` referencing an ACTIVE company
+- Requires a valid `chartOfAccountsId` referencing an ACTIVE CoA
+- Statement type must be one of: BALANCE_SHEET, PROFIT_AND_LOSS, or CASH_FLOW
+- Balance Sheet requires a single reporting date (as-of date)
+- Profit & Loss requires a date range (start date and end date)
+- Cash Flow Statement requires a date range and a method (DIRECT or INDIRECT)
+- The reporting date or date range must fall within a closed or active accounting period
+- Balance Sheet includes only ASSET, LIABILITY, and EQUITY accounts
+- Profit & Loss includes only REVENUE and EXPENSE accounts
+- On a correctly generated Balance Sheet, total assets equal total liabilities plus equity
+- Statement line items are structured by the account group hierarchy from coa-management
+- Accounts not assigned to any group are reported in an "Unclassified" section with warnings
+- Comparative period data, when requested, is aligned to same sections as current period
+- If comparative period trial balance data is unavailable, generation fails with an error
+- Statement is created in DRAFT status
+- A DRAFT statement can be regenerated (replaced) with updated trial balance data
+- Generating for a period with no posted journal entries fails with a validation error
+- Statement output includes subtotals at each level of the account group hierarchy
+- All monetary amounts are denominated in the company's base currency
+- Each statement records a reference to the trial balance snapshot it was generated from
+- Emits an audit event recording the acting user, timestamp, statement type, and parameters
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive generate financial statement request] --> B{Company ACTIVE with ACTIVE CoA?}
+    B -->|No| C[Return error: invalid company or CoA]
+    B -->|Yes| D{Valid statement type?}
+    D -->|No| E[Return error: invalid statement type]
+    D -->|Yes| F{Valid reporting parameters?}
+    F -->|No| G[Return error: invalid parameters]
+    F -->|Yes| H{Trial balance data available?}
+    H -->|No| I[Return error: no trial balance data]
+    H -->|Yes| J[Retrieve trial balance for period]
+    J --> K[Map accounts to statement sections by type]
+    K --> L[Aggregate balances per account group]
+    L --> M{Comparative period requested?}
+    M -->|Yes| N[Retrieve and align prior period data]
+    M -->|No| O[Assemble statement line items]
+    N --> O
+    O --> P[Create FinancialStatement in DRAFT]
+    P --> Q[Emit audit event]
+    Q --> R[Return DRAFT financial statement]
+```
+
+## External Dependencies
+
+- [coa-management::getChartOfAccounts](../../../coa-management/docs/queries/GetChartOfAccounts.md) - Retrieves the active CoA and account group hierarchy for statement structure
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Retrieves GL accounts for type-based classification
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) - Validates that the referenced company is ACTIVE and retrieves base currency
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not ACTIVE
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: Referenced CoA does not exist or is not ACTIVE
+- **INVALID_STATEMENT_TYPE**: Statement type is not BALANCE_SHEET, PROFIT_AND_LOSS, or CASH_FLOW
+- **INVALID_REPORTING_PARAMETERS**: Missing or invalid reporting date, date range, or cash flow method
+- **NO_TRIAL_BALANCE_DATA**: No trial balance data exists for the requested period
+- **COMPARATIVE_DATA_UNAVAILABLE**: Comparative period trial balance data is not available
+
+## Test Cases
+
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when CoA does not exist
+- returns error when CoA is not ACTIVE
+- returns error for invalid statement type
+- returns error when BALANCE_SHEET is missing reportingDate
+- returns error when PROFIT_AND_LOSS is missing date range
+- returns error when CASH_FLOW is missing cashFlowMethod
+- returns error when trial balance does not exist
+- returns error when comparative trial balance does not exist
+- returns error when trial balance has no lines
+- successfully generates a BALANCE_SHEET financial statement
+- successfully generates a PROFIT_AND_LOSS financial statement
+- generates subtotal lines for each section
+- emits audit event recording the generation

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

@@ -0,0 +1,53 @@
+# GeneratePreliminaryStatements
+
+## Overview
+
+generatePreliminaryStatements generates preliminary financial statements (Balance Sheet, Profit & Loss) for the closing period and transitions the PeriodClose from TRIAL_BALANCE_VERIFIED to UNDER_REVIEW status. Preliminary statements can only be generated after the trial balance has been verified, ensuring that all figures are based on a balanced ledger. These statements are generated in DRAFT status for management review and approval.
+
+## Business Rules
+
+- PeriodClose record must exist and be in TRIAL_BALANCE_VERIFIED status
+- Only TRIAL_BALANCE_VERIFIED records can transition to UNDER_REVIEW
+- Preliminary financial statements can only be generated after the trial balance is verified
+- Statements are generated in DRAFT status for review purposes
+- The trial balance must still be balanced at time of generation
+- Updates completionPercentage to reflect progress
+- Records the userId of the operator who generated the preliminary statements
+- Emits an audit event recording the acting user, timestamp, generated statement references, and status transition
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive generate preliminary statements request] --> B{PeriodClose record exists?}
+    B -->|No| C[Return error: period close not found]
+    B -->|Yes| D{PeriodClose in TRIAL_BALANCE_VERIFIED status?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Retrieve verified trial balance for the period]
+    F --> G[Generate preliminary Balance Sheet in DRAFT]
+    G --> H[Generate preliminary Profit & Loss in DRAFT]
+    H --> I[Transition PeriodClose to UNDER_REVIEW]
+    I --> J[Update completionPercentage]
+    J --> K[Emit audit event]
+    K --> L[Return updated PeriodClose with statement references]
+```
+
+## External Dependencies
+
+- [coa-management::getChartOfAccounts](../../../coa-management/docs/queries/GetChartOfAccounts.md) - Retrieves the active CoA and account group hierarchy for statement structure
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) - Retrieves company details and base currency for statement denomination
+
+## Error Scenarios
+
+- **PERIOD_CLOSE_NOT_FOUND**: No PeriodClose record matches the given id
+- **INVALID_STATUS_TRANSITION**: PeriodClose is not in TRIAL_BALANCE_VERIFIED status; only TRIAL_BALANCE_VERIFIED can transition to UNDER_REVIEW
+- **TRIAL_BALANCE_NOT_FOUND**: The verified trial balance for the period no longer exists or is invalid
+
+## Test Cases
+
+- returns error when PeriodClose record does not exist
+- returns error when PeriodClose is in SOFT_LOCKED status
+- returns error when PeriodClose is in IN_PROGRESS status
+- returns error when trial balance is not found
+- generates both BS and P&L and transitions to UNDER_REVIEW with completionPercentage=75
+- emits audit event recording status transition and statement ids

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

@@ -0,0 +1,75 @@
+# GenerateTrialBalance
+
+## Overview
+
+generateTrialBalance creates a point-in-time snapshot report summarizing the balances of all GL accounts for a specific accounting period within a company. The report includes opening balance, period debits, period credits, and closing balance for each account, organized by the account group hierarchy from coa-management. The trial balance supports two variants: PRE_CLOSE (before closing entries) and POST_CLOSE (after closing entries have zeroed temporary accounts). It serves as the fundamental verification mechanism for double-entry bookkeeping and is a prerequisite for financial statement generation.
+
+## Business Rules
+
+- Requires a valid `companyId` referencing a company with an ACTIVE Chart of Accounts
+- Requires a valid `accountingPeriodId` referencing an existing accounting period
+- Requires a variant: PRE_CLOSE or POST_CLOSE
+- Must include all GL accounts from the active CoA, including those with zero balances
+- Opening balance per account equals the closing balance from the immediately preceding period
+- Opening balance for the first period of a new CoA defaults to zero for all accounts
+- Period debits per account equal the sum of all debit amounts from posted journal lines for the period
+- Period credits per account equal the sum of all credit amounts from posted journal lines for the period
+- Closing balance per account equals opening balance plus period debits minus period credits
+- Total debits across all accounts must equal total credits (fundamental equilibrium check)
+- If totals do not balance, an imbalance error is produced with the discrepancy amount
+- Pre-close variant excludes closing entries; post-close variant includes closing entries
+- Post-close variant shows zero balances for all temporary accounts (revenue, expense)
+- Only posted journal entries are included; draft or voided entries are excluded
+- Accounts are ordered by account code in ascending order within each group
+- Balances are organized by account group hierarchy with subtotals at each level
+- Snapshot includes a generation timestamp
+- Regenerating for the same period and variant produces an updated snapshot
+- Generating for a period with no posted entries produces a valid report with zero debits/credits and carried-forward opening balances
+- Emits an audit event recording the acting user, company, period, variant, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive generate trial balance request] --> B{Company has ACTIVE CoA?}
+    B -->|No| C[Return error: no active CoA]
+    B -->|Yes| D{Accounting period exists?}
+    D -->|No| E[Return error: period not found]
+    D -->|Yes| F[Retrieve all GL accounts from active CoA]
+    F --> G[Calculate opening balances from prior period]
+    G --> H[Aggregate period debits and credits from posted journal lines]
+    H --> I[Compute closing balance per account]
+    I --> J{Total debits equal total credits?}
+    J -->|No| K[Return imbalance error with discrepancy amount]
+    J -->|Yes| L[Group balances by account group hierarchy]
+    L --> M[Generate snapshot with timestamp]
+    M --> N[Emit audit event]
+    N --> O[Return trial balance snapshot]
+```
+
+## External Dependencies
+
+- [coa-management::getChartOfAccounts](../../../coa-management/docs/queries/GetChartOfAccounts.md) - Retrieves the active CoA and account group hierarchy
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Retrieves GL accounts for balance aggregation
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) - Validates the referenced company
+
+## Error Scenarios
+
+- **NO_ACTIVE_CHART_OF_ACCOUNTS**: Company does not have an ACTIVE Chart of Accounts
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **TRIAL_BALANCE_IMBALANCED**: Total debits do not equal total credits; includes discrepancy amount
+- **INVALID_VARIANT**: Variant is not PRE_CLOSE or POST_CLOSE
+
+## Test Cases
+
+- returns error when company has no active CoA
+- returns error when accounting period not found
+- returns error when variant is invalid
+- generates trial balance with correct balances for PRE_CLOSE
+- includes zero-balance accounts from active CoA
+- returns error when trial balance is imbalanced
+- emits audit event with correct actor and trial balance details
+- uses accountGroupId from Account record when available
+- zeros closing balances for revenue and expense accounts in POST_CLOSE variant
+- deletes existing TrialBalance before inserting when regenerating for same period and variant
+- sorts trial balance lines by account code ascending

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

@@ -0,0 +1,58 @@
+# InitiatePeriodClose
+
+## Overview
+
+initiatePeriodClose creates a new PeriodClose record in NOT_STARTED status for a given accounting period. This establishes the close checklist that will track the period through the structured close workflow. Only periods in OPEN status can have a close initiated, and each period can have at most one active PeriodClose record.
+
+## Business Rules
+
+- Requires a valid `accountingPeriodId` referencing an existing accounting period
+- The accounting period must be in OPEN status
+- A PeriodClose cannot be initiated for a period that is already CLOSED or PERMANENTLY_CLOSED
+- A PeriodClose cannot be initiated if the period already has an active close record in progress
+- Concurrent close attempts for the same period are rejected with a conflict error
+- The PeriodClose record is created in NOT_STARTED status
+- Records the userId of the operator who initiated the close
+- Sets completionPercentage to 0
+- PeriodClose is scoped to a single AccountingPeriod; each period has at most one active PeriodClose record
+- Emits an audit event via the audit module recording the acting user, timestamp, and period reference
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive initiate period close request] --> B{Accounting period exists?}
+    B -->|No| C[Return error: period not found]
+    B -->|Yes| D{Period in OPEN status?}
+    D -->|No| E[Return error: invalid period status]
+    D -->|Yes| F{Active PeriodClose already exists?}
+    F -->|Yes| G[Return error: close already in progress]
+    F -->|No| H[Create PeriodClose in NOT_STARTED status]
+    H --> I[Record initiating user and set completion to 0%]
+    I --> J[Emit audit event]
+    J --> K[Return PeriodClose record]
+```
+
+## External Dependencies
+
+- None (same-module read for accounting period and period close lookup)
+
+## Error Scenarios
+
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **INVALID_PERIOD_STATUS**: Accounting period is not in OPEN status
+- **CLOSE_ALREADY_IN_PROGRESS**: An active PeriodClose record already exists for this period
+- **CONCURRENT_CLOSE_CONFLICT**: A concurrent close attempt for the same period was detected
+
+## Test Cases
+
+- returns error when accounting period does not exist
+- returns error when accounting period is in NEVER_OPENED status
+- returns error when accounting period is in CLOSED status
+- returns error when accounting period is in PERMANENTLY_CLOSED status
+- returns error when period already has an active close in progress
+- returns error on concurrent close attempt for the same period
+- creates PeriodClose in NOT_STARTED status for an OPEN period
+- records the initiating user's userId
+- sets completionPercentage to 0
+- emits audit event recording acting user, timestamp, and period reference

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

@@ -0,0 +1,44 @@
+# OpenForAdvanceEntry
+
+## Overview
+
+openForAdvanceEntry transitions an accounting period from NEVER_OPENED to FUTURE_ENTERABLE status. This allows advance postings such as recurring journals, accruals, and depreciation entries to be recorded in the period before it is fully opened. This is commonly used when automated entries need to be posted to upcoming periods in advance of the period start date.
+
+## Business Rules
+
+- Period must exist and be in NEVER_OPENED status
+- Only NEVER_OPENED periods can transition to FUTURE_ENTERABLE
+- After transition, the period accepts advance journal postings (e.g., recurring journals, accruals)
+- Emits an audit event recording the status transition, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive openForAdvanceEntry request] --> B{Period exists?}
+    B -->|No| C[Return error: period not found]
+    B -->|Yes| D{Period status is NEVER_OPENED?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Transition period to FUTURE_ENTERABLE]
+    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 NEVER_OPENED status; only NEVER_OPENED can transition to FUTURE_ENTERABLE
+
+## Test Cases
+
+- returns error when accounting period does not exist
+- returns error when period is in FUTURE_ENTERABLE status
+- returns error when period is in OPEN status
+- returns error when period is in CLOSED status
+- returns error when period is in PERMANENTLY_CLOSED status
+- transitions NEVER_OPENED period to FUTURE_ENTERABLE
+- emits audit event recording status transition from NEVER_OPENED to FUTURE_ENTERABLE and acting user

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

@@ -0,0 +1,45 @@
+# OpenPeriod
+
+## Overview
+
+openPeriod transitions an accounting period to OPEN status, enabling standard journal entry postings. The period can transition from either NEVER_OPENED (skipping FUTURE_ENTERABLE) or FUTURE_ENTERABLE. An OPEN period is the primary active state for accepting routine transactional postings from both manual entry and subledger integrations.
+
+## Business Rules
+
+- Period must exist and be in NEVER_OPENED or FUTURE_ENTERABLE status
+- NEVER_OPENED periods can transition directly to OPEN (skipping FUTURE_ENTERABLE)
+- FUTURE_ENTERABLE periods can transition to OPEN
+- After transition, the period accepts all journal entry postings
+- Emits an audit event recording the status transition, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive openPeriod request] --> B{Period exists?}
+    B -->|No| C[Return error: period not found]
+    B -->|Yes| D{Period status is NEVER_OPENED or FUTURE_ENTERABLE?}
+    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 NEVER_OPENED or FUTURE_ENTERABLE status
+
+## Test Cases
+
+- returns error when accounting period does not exist
+- returns error when period is in OPEN status
+- returns error when period is in CLOSED status
+- returns error when period is in PERMANENTLY_CLOSED status
+- transitions NEVER_OPENED period directly to OPEN
+- transitions FUTURE_ENTERABLE period to OPEN
+- emits audit event recording status transition and acting user

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

@@ -0,0 +1,45 @@
+# PermanentlyClosePeriod
+
+## Overview
+
+permanentlyClosePeriod transitions an accounting period from CLOSED to PERMANENTLY_CLOSED status. This is an irreversible operation -- once permanently closed, no further journal entries can be posted to the period regardless of user role, and the period cannot be reopened. This enforces financial statement integrity after external audit finalization and satisfies GAAP/IFRS requirements for period locking.
+
+## Business Rules
+
+- Period must exist and be in CLOSED status
+- Only CLOSED periods can transition to PERMANENTLY_CLOSED
+- The transition is irreversible; PERMANENTLY_CLOSED periods cannot be changed to any other status
+- After transition, all journal entry postings to this period are rejected regardless of user role
+- Emits an audit event recording the irreversible transition, acting user, and timestamp
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive permanentlyClosePeriod 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 PERMANENTLY_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 CLOSED status; only CLOSED periods can transition to PERMANENTLY_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 OPEN status
+- returns error when period is in FUTURE_ENTERABLE status
+- returns error when period is already PERMANENTLY_CLOSED
+- transitions CLOSED period to PERMANENTLY_CLOSED
+- emits audit event recording the irreversible transition and acting user

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

@@ -0,0 +1,61 @@
+# PostAdjustingEntries
+
+## Overview
+
+postAdjustingEntries records adjusting entries (accruals, deferrals, reclassifications) during the period-end close process and transitions the PeriodClose from SUBLEDGERS_VERIFIED to ADJUSTMENTS_POSTED status. Adjusting entries are flagged with an `adjustingEntryType` to distinguish them from regular operational entries for reporting and audit purposes. All adjusting entries must be balanced before the close can proceed.
+
+## Business Rules
+
+- PeriodClose record must exist and be in SUBLEDGERS_VERIFIED status
+- Only SUBLEDGERS_VERIFIED records can transition to ADJUSTMENTS_POSTED
+- Adjusting entries created during this step must have a valid `adjustingEntryType` (ACCRUAL, DEFERRAL, or RECLASSIFICATION)
+- Adjusting entries are flagged distinctly from regular journal entries for audit trail purposes
+- All adjusting entries must be balanced (total debits equal total credits) before the close can proceed
+- Adjusting entries follow the same posting rules as regular journal entries (valid period, valid accounts, etc.)
+- Updates completionPercentage to reflect progress
+- Records the userId of the operator who posted the adjusting entries
+- Emits an audit event recording the acting user, timestamp, adjusting entry details, and status transition
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive post adjusting entries request] --> B{PeriodClose record exists?}
+    B -->|No| C[Return error: period close not found]
+    B -->|Yes| D{PeriodClose in SUBLEDGERS_VERIFIED status?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F{Adjusting entries have valid types?}
+    F -->|No| G[Return error: invalid adjusting entry type]
+    F -->|Yes| H{All adjusting entries balanced?}
+    H -->|No| I[Return error: unbalanced adjusting entries]
+    H -->|Yes| J[Post adjusting entries to the period]
+    J --> K[Transition PeriodClose to ADJUSTMENTS_POSTED]
+    K --> L[Update completionPercentage]
+    L --> M[Emit audit event]
+    M --> N[Return updated PeriodClose]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates GL accounts referenced in adjusting entries
+
+## Error Scenarios
+
+- **PERIOD_CLOSE_NOT_FOUND**: No PeriodClose record matches the given id
+- **INVALID_STATUS_TRANSITION**: PeriodClose is not in SUBLEDGERS_VERIFIED status; only SUBLEDGERS_VERIFIED can transition to ADJUSTMENTS_POSTED
+- **INVALID_ADJUSTING_ENTRY_TYPE**: Adjusting entry type is not ACCRUAL, DEFERRAL, or RECLASSIFICATION
+- **UNBALANCED_ADJUSTING_ENTRIES**: One or more adjusting entries have total debits not equal to total credits
+
+## Test Cases
+
+- returns error when PeriodClose record does not exist
+- returns error when PeriodClose is in IN_PROGRESS status
+- returns error when PeriodClose is already in ADJUSTMENTS_POSTED status
+- returns error when adjusting entry type is invalid
+- returns error when adjusting entries are not balanced
+- posts accrual adjusting entries and transitions to ADJUSTMENTS_POSTED
+- posts deferral adjusting entries and transitions to ADJUSTMENTS_POSTED
+- posts reclassification adjusting entries and transitions to ADJUSTMENTS_POSTED
+- adjusting entries are flagged distinctly from regular journal entries
+- updates completionPercentage after posting adjusting entries
+- emits audit event recording adjusting entry details and status transition

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

@@ -0,0 +1,81 @@
+# PostJournalEntry
+
+## Overview
+
+postJournalEntry transitions a journal entry from DRAFT to POSTED status, making it an immutable part of the general ledger. Posting validates the fundamental accounting constraint (total debits must equal total credits in the functional currency), verifies that the target accounting period is in OPEN or FUTURE_ENTERABLE status, confirms all referenced GL accounts are active, and ensures the entry has at least two journal lines. When a GL account has a successor mapping (deprecated account), the posting is redirected to the successor account.
+
+## Business Rules
+
+- Journal entry must exist and be in DRAFT status
+- Entry must have at least two journal lines
+- Total debits must equal total credits in the functional currency (balance validation)
+- An unbalanced entry cannot be posted
+- The target accounting period must be in OPEN or FUTURE_ENTERABLE status
+- Posting to a NEVER_OPENED, CLOSED, or PERMANENTLY_CLOSED period is rejected
+- All referenced GL accounts must be from an ACTIVE Chart of Accounts
+- Journal lines referencing an inactive or draft GL account are rejected at posting time
+- Journal lines referencing a deprecated GL account with a successor mapping are redirected to the successor account
+- If the successor account is itself inactive or deprecated without a further successor, the posting is rejected
+- Successor account redirect is recorded in the audit trail
+- Once posted, the entry is immutable (no field updates, no line additions or removals)
+- Posted entries cannot be deleted; only reversal is permitted
+- Emits an audit event recording the status transition from DRAFT to POSTED and the posting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive post 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: invalid status for posting]
+    D -->|Yes| F{At least 2 journal lines?}
+    F -->|No| G[Return error: minimum lines not met]
+    F -->|Yes| H{All GL accounts active?}
+    H -->|No| I{Successor account available?}
+    I -->|No| J[Return error: inactive account]
+    I -->|Yes| K[Redirect to successor account]
+    K --> H
+    H -->|Yes| L{Period OPEN or FUTURE_ENTERABLE?}
+    L -->|No| M[Return error: invalid period status]
+    L -->|Yes| N{Debits equal credits in functional currency?}
+    N -->|No| O[Return error: unbalanced entry]
+    N -->|Yes| P[Transition entry to POSTED]
+    P --> Q[Emit audit event]
+    Q --> R[Return posted journal entry]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that all referenced GL accounts are active and resolves successor account mappings
+
+## Error Scenarios
+
+- **JOURNAL_ENTRY_NOT_FOUND**: Referenced journal entry does not exist
+- **INVALID_STATUS_FOR_POSTING**: Journal entry is not in DRAFT status; only DRAFT entries can be posted
+- **MINIMUM_LINES_NOT_MET**: Journal entry has fewer than two journal lines
+- **UNBALANCED_ENTRY**: Total debits do not equal total credits in the functional currency
+- **INVALID_PERIOD_STATUS**: Target accounting period is not in OPEN or FUTURE_ENTERABLE status
+- **INACTIVE_ACCOUNT**: A referenced GL account is inactive or in draft status with no successor mapping
+- **SUCCESSOR_ACCOUNT_INVALID**: A successor account is itself inactive or deprecated without a further successor
+
+## Test Cases
+
+- returns error when journal entry does not exist
+- returns error when journal entry is already POSTED
+- returns error when journal entry is REVERSED
+- returns error when entry has fewer than two journal lines
+- returns error when entry has only one line (debit only or credit only)
+- returns error when total debits do not equal total credits in functional currency
+- returns error when target period is in NEVER_OPENED status
+- returns error when target period is in CLOSED status
+- returns error when target period is in PERMANENTLY_CLOSED status
+- returns error when a GL account is inactive
+- returns error when a GL account is in draft status
+- returns error when successor account is itself inactive without further successor
+- posts balanced DRAFT entry to OPEN period
+- posts balanced DRAFT entry to FUTURE_ENTERABLE period
+- redirects deprecated GL account to successor account at posting time
+- records successor account redirect in audit trail
+- entry becomes immutable after posting
+- emits audit event recording status transition from DRAFT to POSTED and posting user

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

@@ -0,0 +1,72 @@
+# ProcessInventoryHandoff
+
+## Overview
+
+processInventoryHandoff receives inventory valuation events from the inventory module (goods receipts, adjustments, scrap) and creates corresponding Miscellaneous-type journal entries in the general ledger. For goods receipts, the entry debits the inventory asset account and credits the clearing account. For adjustments, it debits the adjustment expense and credits the inventory asset. For scrap, it debits the scrap expense and credits the inventory asset. The command enforces idempotency and supports multi-currency transactions.
+
+## Business Rules
+
+- Receives a handoff event containing the inventory valuation change data and relevant account references
+- Creates a journal entry classified as Miscellaneous journal type
+- For goods receipts: debits inventory asset account and credits the clearing account
+- For adjustments: debits adjustment expense account and credits inventory asset account
+- For scrap: debits scrap expense account and credits inventory asset 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 inventory event
+- 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
+- Emits an audit event recording the source module, document reference, and journal entry created
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive inventory 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{Event type?}
+    H -->|Goods receipt| I[Create entry: debit inventory asset, credit clearing]
+    H -->|Adjustment| J[Create entry: debit adjustment expense, credit inventory asset]
+    H -->|Scrap| K[Create entry: debit scrap expense, credit inventory asset]
+    I --> L[Post journal entry]
+    J --> L
+    K --> L
+    L --> M[Emit audit event]
+    M --> N[Return acknowledgment]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) - Validates that inventory, clearing, and expense 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