Locker module: class master, locker list, waiting list, allotment (tables + client details API)

# Conflicts:
#	fineract-core/src/main/java/org/apache/fineract/commands/service/CommandWrapperBuilder.java
#	fineract-core/src/main/java/org/apache/fineract/infrastructure/jobs/service/JobName.java
#	fineract-provider/src/main/resources/db/changelog/tenant/changelog-tenant.xml

fineract-accounting/src/main/java/org/apache/fineract/accounting/financialactivityaccount/serialization/FinancialActivityAccountDataValidator.java

@@ -45,6 +45,22 @@ public final class FinancialActivityAccountDataValidator {
      */
     private final Set<String> supportedParameters = FinancialActivityAccountsJsonInputParams.getAllValues();
 
+    /**
+     * Activities an administrator may map from the Financial Activity Mappings screen.
+     *
+     * Held in one place because create and update both validate against it, and the two lists had already drifted -
+     * update omitted the two cash activities, and neither offered the dividend activities beyond PAYABLE_DIVIDENDS even
+     * though the accounting code reads them. An activity the posting code resolves but this list omits can only ever be
+     * seeded by a migration, which is how DIVIDEND_PAID and RESERVE_FOR_DIVIDEND came to exist without being editable.
+     */
+    private static final Object[] MAPPABLE_FINANCIAL_ACTIVITIES = { FinancialActivity.ASSET_TRANSFER.getValue(),
+            FinancialActivity.LIABILITY_TRANSFER.getValue(), FinancialActivity.CASH_AT_MAINVAULT.getValue(),
+            FinancialActivity.CASH_AT_TELLER.getValue(), FinancialActivity.OPENING_BALANCES_TRANSFER_CONTRA.getValue(),
+            FinancialActivity.ASSET_FUND_SOURCE.getValue(), FinancialActivity.PAYABLE_DIVIDENDS.getValue(),
+            FinancialActivity.DIVIDEND_PAID.getValue(), FinancialActivity.RESERVE_FOR_DIVIDEND.getValue(),
+            FinancialActivity.DIVIDEND_FORFEITED_INCOME.getValue(), FinancialActivity.DISTRIBUTABLE_PROFIT.getValue(),
+            FinancialActivity.RETAINED_PROFIT.getValue(), FinancialActivity.DIVIDEND_ROUND_OFF.getValue() };
+
     private final String paramNameForFinancialActivity = FinancialActivityAccountsJsonInputParams.FINANCIAL_ACTIVITY_ID.getValue();
     private final String paramNameForGLAccount = FinancialActivityAccountsJsonInputParams.GL_ACCOUNT_ID.getValue();
 
@@ -59,11 +75,8 @@ public final class FinancialActivityAccountDataValidator {
         final JsonElement element = this.fromApiJsonHelper.parse(json);
 
         final Integer financialActivityId = this.fromApiJsonHelper.extractIntegerSansLocaleNamed(paramNameForFinancialActivity, element);
-        baseDataValidator.reset().parameter(paramNameForFinancialActivity).value(financialActivityId).notNull().isOneOfTheseValues(
-                FinancialActivity.ASSET_TRANSFER.getValue(), FinancialActivity.LIABILITY_TRANSFER.getValue(),
-                FinancialActivity.CASH_AT_MAINVAULT.getValue(), FinancialActivity.CASH_AT_TELLER.getValue(),
-                FinancialActivity.OPENING_BALANCES_TRANSFER_CONTRA.getValue(), FinancialActivity.ASSET_FUND_SOURCE.getValue(),
-                FinancialActivity.PAYABLE_DIVIDENDS.getValue());
+        baseDataValidator.reset().parameter(paramNameForFinancialActivity).value(financialActivityId).notNull()
+                .isOneOfTheseValues(MAPPABLE_FINANCIAL_ACTIVITIES);
 
         final Long glAccountId = this.fromApiJsonHelper.extractLongNamed(paramNameForGLAccount, element);
         baseDataValidator.reset().parameter(paramNameForGLAccount).value(glAccountId).notNull().integerGreaterThanZero();
@@ -86,10 +99,8 @@ public final class FinancialActivityAccountDataValidator {
         if (this.fromApiJsonHelper.parameterExists(paramNameForFinancialActivity, element)) {
             final Integer financialActivityId = this.fromApiJsonHelper.extractIntegerSansLocaleNamed(paramNameForFinancialActivity,
                     element);
-            baseDataValidator.reset().parameter(paramNameForFinancialActivity).value(financialActivityId).ignoreIfNull().isOneOfTheseValues(
-                    FinancialActivity.ASSET_TRANSFER.getValue(), FinancialActivity.LIABILITY_TRANSFER.getValue(),
-                    FinancialActivity.OPENING_BALANCES_TRANSFER_CONTRA.getValue(), FinancialActivity.ASSET_FUND_SOURCE.getValue(),
-                    FinancialActivity.PAYABLE_DIVIDENDS.getValue());
+            baseDataValidator.reset().parameter(paramNameForFinancialActivity).value(financialActivityId).ignoreIfNull()
+                    .isOneOfTheseValues(MAPPABLE_FINANCIAL_ACTIVITIES);
         }
 
         if (this.fromApiJsonHelper.parameterExists(paramNameForGLAccount, element)) {

fineract-accounting/src/main/java/org/apache/fineract/accounting/journalentry/exception/JournalEntryInvalidException.java

@@ -37,6 +37,7 @@ public class JournalEntryInvalidException extends AbstractPlatformDomainRuleExce
         DEBIT_CREDIT_ACCOUNT_OR_AMOUNT_EMPTY, //
         GL_ACCOUNT_DISABLED, //
         GL_ACCOUNT_MANUAL_ENTRIES_NOT_PERMITTED, //
+        GL_ACCOUNT_IS_HEADER, //
         INVALID_DEBIT_OR_CREDIT_ACCOUNTS; //
 
         public String errorMessage() {
@@ -58,6 +59,8 @@ public class JournalEntryInvalidException extends AbstractPlatformDomainRuleExce
                 return "Invalid debit or credit accounts are passed";
             } else if (name().equalsIgnoreCase("GL_ACCOUNT_MANUAL_ENTRIES_NOT_PERMITTED")) {
                 return "Target account does not allow manual adjustments";
+            } else if (name().equalsIgnoreCase("GL_ACCOUNT_IS_HEADER")) {
+                return "Target account is a Header account (a chart-of-accounts grouping node) and cannot receive a transaction directly";
             }
             return name();
         }
@@ -79,6 +82,8 @@ public class JournalEntryInvalidException extends AbstractPlatformDomainRuleExce
                 return "error.msg.glJournalEntry.invalid.debit.or.credit.accounts";
             } else if (name().equalsIgnoreCase("GL_ACCOUNT_MANUAL_ENTRIES_NOT_PERMITTED")) {
                 return "error.msg.glJournalEntry.invalid.account.manual.adjustments.not.permitted";
+            } else if (name().equalsIgnoreCase("GL_ACCOUNT_IS_HEADER")) {
+                return "error.msg.glJournalEntry.invalid.account.is.header";
             }
             return name();
         }

fineract-accounting/src/main/java/org/apache/fineract/accounting/producttoaccountmapping/serialization/ProductToGLAccountMappingFromApiJsonDeserializer.java

@@ -279,9 +279,15 @@ public final class ProductToGLAccountMappingFromApiJsonDeserializer {
 
         if (AccountingValidations.isCashBasedAccounting(accountingRuleType)) {
 
+            // Optional, not mandatory like the three below: it names an account for cash physically
+            // received at the counter for a share purchase, which every register in this bank now
+            // books against the account the money actually reached instead. Left absent, a product
+            // simply carries no such mapping, and any code path that still needs one (a genuine
+            // over-the-counter collection) fails with a named "GL not mapped" error rather than
+            // silently assuming the till.
             final Long shareReferenceId = this.fromApiJsonHelper.extractLongNamed(SharesProductAccountingParams.SHARES_REFERENCE.getValue(),
                     element);
-            baseDataValidator.reset().parameter(SharesProductAccountingParams.SHARES_REFERENCE.getValue()).value(shareReferenceId).notNull()
+            baseDataValidator.reset().parameter(SharesProductAccountingParams.SHARES_REFERENCE.getValue()).value(shareReferenceId)
                     .integerGreaterThanZero();
 
             final Long shareSuspenseId = this.fromApiJsonHelper.extractLongNamed(SharesProductAccountingParams.SHARES_SUSPENSE.getValue(),

fineract-accounting/src/main/java/org/apache/fineract/accounting/producttoaccountmapping/service/ProductToGLAccountMappingReadPlatformServiceImpl.java

@@ -426,6 +426,8 @@ public class ProductToGLAccountMappingReadPlatformServiceImpl implements Product
                     accountMappingDetails.put(SavingProductAccountingDataParams.INCOME_FROM_INTEREST.getValue(), glAccountData);
                 } else if (glAccountForSavings.equals(AccrualAccountsForSavings.ESCHEAT_LIABILITY)) {
                     accountMappingDetails.put(SavingProductAccountingDataParams.ESCHEAT_LIABILITY.getValue(), glAccountData);
+                } else if (glAccountForSavings.equals(AccrualAccountsForSavings.ROUNDING_ADJUSTMENT)) {
+                    accountMappingDetails.put(SavingProductAccountingDataParams.ROUNDING_ADJUSTMENT.getValue(), glAccountData);
                     // Expense
                 } else if (glAccountForSavings.equals(AccrualAccountsForSavings.INTEREST_ON_SAVINGS)) {
                     accountMappingDetails.put(SavingProductAccountingDataParams.INTEREST_ON_SAVINGS.getValue(), glAccountData);
@@ -470,6 +472,8 @@ public class ProductToGLAccountMappingReadPlatformServiceImpl implements Product
                     accountMappingDetails.put(SavingProductAccountingDataParams.INCOME_FROM_INTEREST.getValue(), glAccountData);
                 } else if (glAccountForSavings.equals(CashAccountsForSavings.ESCHEAT_LIABILITY)) {
                     accountMappingDetails.put(SavingProductAccountingDataParams.ESCHEAT_LIABILITY.getValue(), glAccountData);
+                } else if (glAccountForSavings.equals(CashAccountsForSavings.ROUNDING_ADJUSTMENT)) {
+                    accountMappingDetails.put(SavingProductAccountingDataParams.ROUNDING_ADJUSTMENT.getValue(), glAccountData);
                     // Expense
                 } else if (glAccountForSavings.equals(CashAccountsForSavings.INTEREST_ON_SAVINGS)) {
                     accountMappingDetails.put(SavingProductAccountingDataParams.INTEREST_ON_SAVINGS.getValue(), glAccountData);

fineract-accounting/src/main/java/org/apache/fineract/accounting/producttoaccountmapping/service/SavingsProductToGLAccountMappingHelper.java

@@ -106,6 +106,20 @@ public class SavingsProductToGLAccountMappingHelper extends ProductToGLAccountMa
                 PortfolioProductType.SAVING);
     }
 
+    /**
+     * Create-or-merge, for an expense row a product may not have yet.
+     *
+     * The plain merge variant assumes the mapping already exists, which is true of every expense
+     * row that shipped with the product screen. A row added later — the rounding adjustment — is
+     * absent on every product created before it, so editing one of those has to create the
+     * mapping rather than fail looking for it.
+     */
+    public void createOrmergeSavingsToExpenseAccountMappingChanges(final JsonElement element, final String paramName,
+            final Long productId, final int accountTypeId, final Map<String, Object> changes) {
+        createOrmergeProductToAccountMappingChanges(element, paramName, productId, accountTypeId, changes, GLAccountType.EXPENSE,
+                PortfolioProductType.SAVING);
+    }
+
     /*** Abstractions for payments channel related to savings products ***/
 
     public void savePaymentChannelToFundSourceMappings(final JsonCommand command, final JsonElement element, final Long productId,
@@ -248,6 +262,8 @@ public class SavingsProductToGLAccountMappingHelper extends ProductToGLAccountMa
                         CashAccountsForSavings.TRANSFERS_SUSPENSE.toString(), changes);
                 createOrmergeSavingsToLiabilityAccountMappingChanges(element, SavingProductAccountingParams.ESCHEAT_LIABILITY.getValue(),
                         savingsProductId, CashAccountsForSavings.ESCHEAT_LIABILITY.getValue(), changes);
+                createOrmergeSavingsToExpenseAccountMappingChanges(element, SavingProductAccountingParams.ROUNDING_ADJUSTMENT.getValue(),
+                        savingsProductId, CashAccountsForSavings.ROUNDING_ADJUSTMENT.getValue(), changes);
             break;
             case ACCRUAL_PERIODIC:
                 // asset
@@ -308,6 +324,8 @@ public class SavingsProductToGLAccountMappingHelper extends ProductToGLAccountMa
 
                 createOrmergeSavingsToLiabilityAccountMappingChanges(element, SavingProductAccountingParams.ESCHEAT_LIABILITY.getValue(),
                         savingsProductId, AccrualAccountsForSavings.ESCHEAT_LIABILITY.getValue(), changes);
+                createOrmergeSavingsToExpenseAccountMappingChanges(element, SavingProductAccountingParams.ROUNDING_ADJUSTMENT.getValue(),
+                        savingsProductId, AccrualAccountsForSavings.ROUNDING_ADJUSTMENT.getValue(), changes);
 
             break;
             case ACCRUAL_UPFRONT:

fineract-accounting/src/main/java/org/apache/fineract/accounting/producttoaccountmapping/service/ShareProductToGLAccountMappingHelper.java

@@ -27,6 +27,7 @@ import org.apache.fineract.accounting.common.AccountingRuleType;
 import org.apache.fineract.accounting.glaccount.domain.GLAccountRepository;
 import org.apache.fineract.accounting.glaccount.domain.GLAccountRepositoryWrapper;
 import org.apache.fineract.accounting.glaccount.domain.GLAccountType;
+import org.apache.fineract.accounting.producttoaccountmapping.domain.ProductToGLAccountMapping;
 import org.apache.fineract.accounting.producttoaccountmapping.domain.ProductToGLAccountMappingRepository;
 import org.apache.fineract.infrastructure.codes.domain.CodeValueRepository;
 import org.apache.fineract.infrastructure.core.api.JsonCommand;
@@ -166,9 +167,9 @@ public class ShareProductToGLAccountMappingHelper extends ProductToGLAccountMapp
             case NONE:
             break;
             case CASH_BASED:
-                // asset
-                mergeSharesToAssetAccountMappingChanges(element, SharesProductAccountingParams.SHARES_REFERENCE.getValue(), sharesProductId,
-                        CashAccountsForShares.SHARES_REFERENCE.getValue(), CashAccountsForShares.SHARES_REFERENCE.toString(), changes);
+                // asset -- the one optional mapping here, so unlike the three below it needs its own
+                // handling for the case the field is now absent (see mergeOrRemoveSharesReferenceMapping).
+                mergeOrRemoveSharesReferenceMapping(element, sharesProductId, changes);
 
                 // income
                 mergeSharesToIncomeAccountMappingChanges(element, SharesProductAccountingParams.INCOME_FROM_FEES.getValue(),
@@ -194,4 +195,35 @@ public class ShareProductToGLAccountMappingHelper extends ProductToGLAccountMapp
     public void deleteSharesProductToGLAccountMapping(final Long sharesProductId) {
         deleteProductToGLAccountMapping(sharesProductId, PortfolioProductType.SHARES);
     }
+
+    /**
+     * Handles the one optional share-product mapping, Shares Reference, on an edit that does not change
+     * the accounting rule.
+     *
+     * <p>
+     * The other three mappings (Suspense, Income From Fees, Equity) are mandatory, so
+     * {@code mergeProductToAccountMappingChanges} only ever needs to handle "present and possibly
+     * changed" for them -- a null value there cannot happen without failing validation first. Shares
+     * Reference can legitimately be absent, and the shared merge helper (used across loan, savings and
+     * share products alike) only handles "present": it silently leaves an existing mapping row alone
+     * when the incoming value is null, rather than clearing it. Editing this one field out of an
+     * existing product would otherwise leave the product still carrying its old GL underneath, invisible
+     * on the edit form but still resolvable by any code path that looks it up directly.
+     */
+    private void mergeOrRemoveSharesReferenceMapping(final JsonElement element, final Long sharesProductId,
+            final Map<String, Object> changes) {
+        final Long shareReferenceId = this.fromApiJsonHelper.extractLongNamed(SharesProductAccountingParams.SHARES_REFERENCE.getValue(),
+                element);
+        if (shareReferenceId != null) {
+            mergeSharesToAssetAccountMappingChanges(element, SharesProductAccountingParams.SHARES_REFERENCE.getValue(), sharesProductId,
+                    CashAccountsForShares.SHARES_REFERENCE.getValue(), CashAccountsForShares.SHARES_REFERENCE.toString(), changes);
+            return;
+        }
+        final ProductToGLAccountMapping existing = this.accountMappingRepository.findCoreProductToFinAccountMapping(sharesProductId,
+                PortfolioProductType.SHARES.getValue(), CashAccountsForShares.SHARES_REFERENCE.getValue());
+        if (existing != null) {
+            this.accountMappingRepository.delete(existing);
+            changes.put(SharesProductAccountingParams.SHARES_REFERENCE.getValue(), null);
+        }
+    }
 }

fineract-core/src/main/java/org/apache/fineract/accounting/common/AccountingConstants.java

@@ -269,7 +269,15 @@ public final class AccountingConstants {
         OVERDRAFT_PORTFOLIO_CONTROL(11), //
         INCOME_FROM_INTEREST(12), //
         LOSSES_WRITTEN_OFF(13), //
-        ESCHEAT_LIABILITY(14); //
+        ESCHEAT_LIABILITY(14), //
+        /**
+         * Where the paise dropped from a cash closure are absorbed.
+         *
+         * Cash has no paise in circulation, so a closing balance of 9,883.79 is handed over as
+         * 9,883 and the 0.79 has to land somewhere other than the member's own ledger. Numbered
+         * well clear of the accrual slots so the two sets never collide as either grows.
+         */
+        ROUNDING_ADJUSTMENT(26); //
 
         private final Integer value;
 
@@ -317,7 +325,9 @@ public final class AccountingConstants {
         FEES_RECEIVABLE(15), //
         PENALTIES_RECEIVABLE(16), //
         INTEREST_PAYABLE(17), //
-        INTEREST_RECEIVABLE(18);
+        INTEREST_RECEIVABLE(18), //
+        /** Where the paise dropped from a cash closure are absorbed — see the cash enum. */
+        ROUNDING_ADJUSTMENT(26);
 
         private final Integer value;
 
@@ -372,7 +382,8 @@ public final class AccountingConstants {
         PENALTIES_RECEIVABLE("penaltiesReceivableAccountId"), //
         INTEREST_RECEIVABLE("interestReceivableAccountId"), //
         FEES_RECEIVABLE("feesReceivableAccountId"), //
-        INTEREST_PAYABLE("interestPayableAccountId");
+        INTEREST_PAYABLE("interestPayableAccountId"), //
+        ROUNDING_ADJUSTMENT("roundingAdjustmentAccountId");
 
         private final String value;
 
@@ -410,7 +421,8 @@ public final class AccountingConstants {
         FEES_RECEIVABLE("feeReceivableAccount"), //
         PENALTIES_RECEIVABLE("penaltyReceivableAccount"), //
         INTEREST_PAYABLE("interestPayableAccount"), //
-        INTEREST_RECEIVABLE("interestReceivableAccount"); //
+        INTEREST_RECEIVABLE("interestReceivableAccount"), //
+        ROUNDING_ADJUSTMENT("roundingAdjustmentAccount"); //
 
         private final String value;
 
@@ -439,7 +451,32 @@ public final class AccountingConstants {
         PAYABLE_DIVIDENDS(201, "payableDividends", GLAccountType.LIABILITY), //
         DIVIDEND_PAID(202, "dividendPaid", GLAccountType.LIABILITY), //
         RESERVE_FOR_DIVIDEND(301, "reserveForDividend", GLAccountType.EQUITY), //
-        DIVIDEND_FORFEITED_INCOME(400, "dividendForfeitedIncome", GLAccountType.INCOME); //
+        DIVIDEND_FORFEITED_INCOME(400, "dividendForfeitedIncome", GLAccountType.INCOME), //
+        /**
+         * The year's closed-out profit a dividend is declared against.
+         *
+         * Kept apart from {@link #RETAINED_PROFIT} on purpose: a declaration is sized on this balance, so anything that
+         * has already been through a distribution decision must not sit here, or the same money would be offered for
+         * distribution a second time.
+         */
+        DISTRIBUTABLE_PROFIT(302, "distributableProfit", GLAccountType.EQUITY), //
+        /**
+         * Where profit settles once it is no longer distributable - the remainder left after an approved declaration
+         * and dividends forfeited after the three-year claim window. Nothing here ever enters a later dividend
+         * calculation.
+         */
+        RETAINED_PROFIT(303, "retainedProfit", GLAccountType.EQUITY), //
+        /**
+         * Where the paise a dividend cannot divide evenly are collected.
+         *
+         * A declaration of 1,538.91 that allocates 1,538 to members leaves 0.91 that belongs to nobody. It used to be
+         * swept into retained profit along with the undistributed remainder, which buried an arithmetic artefact inside
+         * a figure the society reads as a real business result. Given its own account it stays separately readable -
+         * and an auditor asking why members received less than was declared can be answered from the ledger.
+         *
+         * Optional: a society that has not mapped it has the residue swept to retained profit exactly as before.
+         */
+        DIVIDEND_ROUND_OFF(304, "dividendRoundOff", GLAccountType.EQUITY); //
 
         private final Integer value;
         private final String code;

fineract-core/src/main/java/org/apache/fineract/commands/service/CommandSourceService.java

@@ -164,12 +164,24 @@ public class CommandSourceService {
                 || "SHAREPRODUCT".equalsIgnoreCase(commandSource.getEntityName())
                 || "FIXEDDEPOSITPRODUCT".equalsIgnoreCase(commandSource.getEntityName())
                 || "USER".equalsIgnoreCase(commandSource.getEntityName())
-                || "ROLE".equalsIgnoreCase(commandSource.getEntityName())) {
+                || "ROLE".equalsIgnoreCase(commandSource.getEntityName())
+                || isDdsEntity(commandSource.getEntityName())) {
             return false;
         }
         return true;
     }
 
+    /**
+     * The DDS module's maker-checker entities. A super user's DDS work goes to a checker like anyone
+     * else's: DDS moves customers' money, and every such move is to be approved by a second person.
+     */
+    public static boolean isDdsEntity(final String entityName) {
+        return entityName != null && switch (entityName.toUpperCase()) {
+            case "PARTY", "AGENT", "PARTYTRANSACTION", "DDSACCOUNTTYPE", "COMMISSIONSLAB", "DDSBATCH", "DDSCOLLECTIONENTRY" -> true;
+            default -> false;
+        };
+    }
+
     private void sanitizeJson(@NonNull CommandSource commandSource, Set<String> sanitizeKeys) {
         if (sanitizeKeys == null || sanitizeKeys.isEmpty()) {
             return;

fineract-core/src/main/java/org/apache/fineract/commands/service/CommandWrapperBuilder.java

@@ -95,6 +95,54 @@ public class CommandWrapperBuilder {
         return this;
     }
 
+    public CommandWrapperBuilder createLockerClass() {
+        this.actionName = "CREATE";
+        this.entityName = "LOCKERCLASS";
+        this.entityId = null;
+        this.href = "/lockerclasses";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateLockerClass(final Long lockerClassId) {
+        this.actionName = "UPDATE";
+        this.entityName = "LOCKERCLASS";
+        this.entityId = lockerClassId;
+        this.href = "/lockerclasses/" + lockerClassId;
+        return this;
+    }
+
+    public CommandWrapperBuilder deleteLockerClass(final Long lockerClassId) {
+        this.actionName = "DELETE";
+        this.entityName = "LOCKERCLASS";
+        this.entityId = lockerClassId;
+        this.href = "/lockerclasses/" + lockerClassId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createLockerWaitingList() {
+        this.actionName = "CREATE";
+        this.entityName = "LOCKERWAITINGLIST";
+        this.entityId = null;
+        this.href = "/lockerwaitinglist";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateLockerWaitingList(final Long waitingListId) {
+        this.actionName = "UPDATE";
+        this.entityName = "LOCKERWAITINGLIST";
+        this.entityId = waitingListId;
+        this.href = "/lockerwaitinglist/" + waitingListId;
+        return this;
+    }
+
+    public CommandWrapperBuilder cancelLockerWaitingList(final Long waitingListId) {
+        this.actionName = "CANCEL";
+        this.entityName = "LOCKERWAITINGLIST";
+        this.entityId = waitingListId;
+        this.href = "/lockerwaitinglist/" + waitingListId + "?command=cancel";
+        return this;
+    }
+
     public CommandWrapperBuilder createChequeStockLot() {
         this.actionName = "CREATE";
         this.entityName = "CHEQUESTOCKLOT";
@@ -664,6 +712,175 @@ public class CommandWrapperBuilder {
         return this;
     }
 
+    public CommandWrapperBuilder createAgent() {
+        this.actionName = "CREATE";
+        this.entityName = "AGENT";
+        this.entityId = null;
+        this.href = "/dds/agents/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateAgent(final Long agentId) {
+        this.actionName = "UPDATE";
+        this.entityName = "AGENT";
+        this.entityId = agentId;
+        this.href = "/dds/agents/" + agentId;
+        return this;
+    }
+
+    public CommandWrapperBuilder closeAgent(final Long agentId) {
+        this.actionName = "CLOSE";
+        this.entityName = "AGENT";
+        this.entityId = agentId;
+        this.href = "/dds/agents/" + agentId + "?command=close";
+        return this;
+    }
+
+    public CommandWrapperBuilder createParty() {
+        this.actionName = "CREATE";
+        this.entityName = "PARTY";
+        this.entityId = null;
+        this.href = "/dds/parties/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateParty(final Long partyId) {
+        this.actionName = "UPDATE";
+        this.entityName = "PARTY";
+        this.entityId = partyId;
+        this.href = "/dds/parties/" + partyId;
+        return this;
+    }
+
+    public CommandWrapperBuilder closeParty(final Long partyId) {
+        this.actionName = "CLOSE";
+        this.entityName = "PARTY";
+        this.entityId = partyId;
+        this.href = "/dds/parties/" + partyId + "?command=close";
+        return this;
+    }
+
+    /**
+     * Pays a matured DDS account out and closes it. A separate action from CLOSE because it moves
+     * money, and so is worth its own permission and its own line in the audit trail.
+     */
+    public CommandWrapperBuilder payOutParty(final Long partyId) {
+        this.actionName = "PAYOUT";
+        this.entityName = "PARTY";
+        this.entityId = partyId;
+        this.href = "/dds/parties/" + partyId + "?command=payout";
+        return this;
+    }
+
+    /**
+     * Closes a DDS account before its term is up, settling the shortfall against the customer or the
+     * agent. Separate from both CLOSE and PAYOUT because it is the only one of the three that changes
+     * what a customer is owed, so a bank will want it approved by someone other than whoever raised it.
+     */
+    public CommandWrapperBuilder prematureCloseParty(final Long partyId) {
+        this.actionName = "PREMATURECLOSE";
+        this.entityName = "PARTY";
+        this.entityId = partyId;
+        this.href = "/dds/parties/" + partyId + "?command=prematureclose";
+        return this;
+    }
+
+    public CommandWrapperBuilder prematureCloseOverrideParty(final Long partyId) {
+        this.actionName = "PREMATURECLOSEOVERRIDE";
+        this.entityName = "PARTY";
+        this.entityId = partyId;
+        this.href = "/dds/parties/" + partyId + "?command=prematurecloseoverride";
+        return this;
+    }
+
+    public CommandWrapperBuilder createDdsAccountType() {
+        this.actionName = "CREATE";
+        this.entityName = "DDSACCOUNTTYPE";
+        this.entityId = null;
+        this.href = "/dds/accounttypes/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateDdsAccountType(final Long accountTypeId) {
+        this.actionName = "UPDATE";
+        this.entityName = "DDSACCOUNTTYPE";
+        this.entityId = accountTypeId;
+        this.href = "/dds/accounttypes/" + accountTypeId;
+        return this;
+    }
+
+    public CommandWrapperBuilder createPartyTransaction() {
+        this.actionName = "CREATE";
+        this.entityName = "PARTYTRANSACTION";
+        this.entityId = null;
+        this.href = "/dds/partytransactions/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder createDdsCollectionEntries() {
+        this.actionName = "CREATE";
+        this.entityName = "DDSCOLLECTIONENTRY";
+        this.entityId = null;
+        this.href = "/dds/collectionentries/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder cancelDdsCollectionEntry(final Long entryId) {
+        this.actionName = "CANCEL";
+        this.entityName = "DDSCOLLECTIONENTRY";
+        this.entityId = entryId;
+        this.href = "/dds/collectionentries/" + entryId;
+        return this;
+    }
+
+    public CommandWrapperBuilder settleDdsCollectionEntries() {
+        this.actionName = "SETTLE";
+        this.entityName = "DDSCOLLECTIONENTRY";
+        this.entityId = null;
+        this.href = "/dds/collectionentries/settle";
+        return this;
+    }
+
+    public CommandWrapperBuilder createCommissionSlabs() {
+        this.actionName = "CREATE";
+        this.entityName = "COMMISSIONSLAB";
+        this.entityId = null;
+        this.href = "/dds/commissionslabs/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder updateCommissionSlab(final Long slabId) {
+        this.actionName = "UPDATE";
+        this.entityName = "COMMISSIONSLAB";
+        this.entityId = slabId;
+        this.href = "/dds/commissionslabs/" + slabId;
+        return this;
+    }
+
+    public CommandWrapperBuilder generateDdsBatchRun() {
+        this.actionName = "GENERATE";
+        this.entityName = "DDSBATCH";
+        this.entityId = null;
+        this.href = "/dds/batchruns/template";
+        return this;
+    }
+
+    public CommandWrapperBuilder postDdsBatchRun(final Long batchRunId) {
+        this.actionName = "POST";
+        this.entityName = "DDSBATCH";
+        this.entityId = batchRunId;
+        this.href = "/dds/batchruns/" + batchRunId;
+        return this;
+    }
+
+    public CommandWrapperBuilder deleteOffice(final Long officeId) {
+        this.actionName = "DELETE";
+        this.entityName = "OFFICE";
+        this.entityId = officeId;
+        this.href = "/offices/" + officeId;
+        return this;
+    }
+
     public CommandWrapperBuilder createOfficeTransaction() {
         this.actionName = "CREATE";
         this.entityName = "OFFICETRANSACTION";

fineract-core/src/main/java/org/apache/fineract/commands/service/PortfolioCommandSourceWritePlatformServiceImpl.java

@@ -123,7 +123,9 @@ public class PortfolioCommandSourceWritePlatformServiceImpl implements Portfolio
         AppUser appUser = this.context.authenticatedUser();
         String permissionCode = commandSource.getPermissionCode();
         appUser.validateHasCheckerPermissionTo(permissionCode);
-        if (!configurationService.isSameMakerCheckerEnabled() && !appUser.isCheckerSuperUser()) {
+        // A DDS entry is never checked by the user who made it, super user or not - see CommandSourceService.isDdsEntity.
+        if (!configurationService.isSameMakerCheckerEnabled()
+                && (!appUser.isCheckerSuperUser() || CommandSourceService.isDdsEntity(commandSource.getEntityName()))) {
             AppUser maker = commandSource.getMaker();
             if (maker == null) {
                 throw new UnsupportedCommandException(permissionCode, "Maker user is missing.");

fineract-core/src/main/java/org/apache/fineract/infrastructure/jobs/service/JobName.java

@@ -56,6 +56,7 @@ public enum JobName {
     EXECUTE_DIRTY_JOBS("Execute All Dirty Jobs"), //
     INCREASE_BUSINESS_DATE_BY_1_DAY("Increase Business Date by 1 day"), //
     INCREASE_COB_DATE_BY_1_DAY("Increase COB Date by 1 day"), //
+    SYNC_BUSINESS_DATE_TO_SYSTEM_DATE("Sync Business Date To System Date"), //
     LOAN_COB("Loan COB"), //
     LOAN_DELINQUENCY_CLASSIFICATION("Loan Delinquency Classification"), //
     SEND_ASYNCHRONOUS_EVENTS("Send Asynchronous Events"), //
@@ -71,6 +72,8 @@ public enum JobName {
     OUTWARD_CLEARING_BATCH_SEND("CTS Outward Clearing Batch Send"), //
     CTR_REPORT_GENERATION("AML Monthly CTR Report Generation"), //
     AML_STR_WEEKLY_DIGEST("AML STR Weekly Digest"), //
+    POST_DDS_INTEREST("Post DDS Interest"), //
+    CLIENT_BEHAVIOUR_WINDOW("Client Behaviour Window Computation"), //
     ; //
 
     private final String name;

fineract-core/src/main/java/org/apache/fineract/organisation/agent/data/AgentData.java

@@ -0,0 +1,99 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.Collection;
+import lombok.Builder;
+import lombok.Getter;
+
+/**
+ * Immutable data object representing a DDS agent and its guarantors, following the legacy Agent
+ * Master Entry screen. Built via the Lombok builder rather than a long positional constructor, as the
+ * other DDS data objects are.
+ *
+ * The commission block below is on the legacy SubAgent Master screen rather than the Agent one, and
+ * drives the commission batch.
+ */
+@Getter
+@Builder(toBuilder = true)
+public final class AgentData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long clientId;
+    private final String clientName;
+    private final String agentCode;
+    private final String agentNameId;
+    private final String agentAddress1;
+    private final String agentAddress2;
+    private final String agentCity;
+    private final String agentPinCode;
+    private final String agentTelephone;
+    private final String agentSavingAccountType;
+    private final String agentSavingAccountNo;
+    private final LocalDate agentOpeningDate;
+    private final LocalDate agentBirthDate;
+    private final BigDecimal agentCurrentBalance;
+    private final BigDecimal agentOpeningBalance;
+
+    /**
+     * The branch this agent belongs to. {@code officeId} is what the screen sends back on an edit;
+     * {@code homeBranch} is that office's current name, read from the office row rather than from
+     * the agent, so a renamed branch reads correctly here without the agent being touched.
+     */
+    private final Long officeId;
+    private final String homeBranch;
+
+    /**
+     * The ledger account this agent's collections pass through, if the bank gave them one. The id is
+     * what the screen sends back on an edit; the code and name are what it shows.
+     */
+    private final Long glAccountId;
+    private final String glAccountCode;
+    private final String glAccountName;
+
+    /** Commission owed but not yet paid out, and the TDS withheld so far. Both are batch outcomes. */
+    private final BigDecimal commission;
+    private final BigDecimal tdsAmount;
+
+    /** Commission settings and the standing figures the commission run deducts. */
+    private final boolean commissionCalculation;
+    private final boolean tdsApplicable;
+    private final BigDecimal tdsPercent;
+    private final BigDecimal deductCommission;
+    private final BigDecimal agentDeposit;
+    private final BigDecimal festivalAdvance;
+    private final BigDecimal otherDeduction;
+
+    private final boolean active;
+
+    /** When the relationship ended, or null while the agent is on the books. */
+    private final LocalDate closeDate;
+
+    private final LocalDateTime createdDate;
+    private final LocalDateTime lastModifiedDate;
+    private final Collection<AgentGuarantorData> guarantors;
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/data/AgentGuarantorData.java

@@ -0,0 +1,59 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import lombok.Getter;
+
+/**
+ * Immutable data object representing a single agent guarantor.
+ */
+@Getter
+public final class AgentGuarantorData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long clientId;
+    private final String guarantorName;
+    private final String address1;
+    private final String address2;
+    private final String city;
+    private final String pinCode;
+    private final String telephone;
+
+    public static AgentGuarantorData instance(final Long id, final Long clientId, final String guarantorName, final String address1,
+            final String address2, final String city, final String pinCode, final String telephone) {
+        return new AgentGuarantorData(id, clientId, guarantorName, address1, address2, city, pinCode, telephone);
+    }
+
+    private AgentGuarantorData(final Long id, final Long clientId, final String guarantorName, final String address1,
+            final String address2, final String city, final String pinCode, final String telephone) {
+        this.id = id;
+        this.clientId = clientId;
+        this.guarantorName = guarantorName;
+        this.address1 = address1;
+        this.address2 = address2;
+        this.city = city;
+        this.pinCode = pinCode;
+        this.telephone = telephone;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/domain/Agent.java

@@ -0,0 +1,523 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.domain;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Consumer;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.accounting.glaccount.domain.GLAccount;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+import org.apache.fineract.organisation.office.domain.Office;
+import org.apache.fineract.portfolio.client.domain.Client;
+
+/**
+ * A DDS (Daily Deposit Scheme) collection agent. Can represent either a person or, at the top of the
+ * hierarchy, the bank itself acting as its own agent. Holds its own settlement savings account and one
+ * or more guarantors.
+ *
+ * The field set follows the legacy Agent Master Entry screen. SubAgent was folded into Agent
+ * (2026-08-24) so the Agent now does the daily collection work directly, but the SubAgent-only fields
+ * that came across with it (TDS, transfer/security accounts, machine rent, collection-limit history)
+ * were on no screen the business uses and were read by no query, report or job, so they were dropped
+ * again in 0481. Two fields are kept despite not appearing on that screen, because code reads them:
+ * {@code commission}/{@code lastCommissionDate}, and the deduction figures the Agent Commission
+ * Statement reports.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_agent", uniqueConstraints = { @UniqueConstraint(columnNames = { "agent_code" }, name = "agent_code_UNIQUE") })
+public class Agent extends AbstractAuditableCustom {
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @Column(name = "agent_code", length = 20, nullable = false)
+    private String agentCode;
+
+    @Column(name = "agent_name", length = 100, nullable = false)
+    private String agentName;
+
+    @Column(name = "agent_address1", length = 200, nullable = false)
+    private String agentAddress1;
+
+    @Column(name = "agent_address2", length = 200)
+    private String agentAddress2;
+
+    @Column(name = "agent_city", length = 100, nullable = false)
+    private String agentCity;
+
+    @Column(name = "agent_pincode", length = 20, nullable = false)
+    private String agentPinCode;
+
+    @Column(name = "agent_telephone", length = 20)
+    private String agentTelephone;
+
+    @Column(name = "agent_saving_account_type", length = 100, nullable = false)
+    private String agentSavingAccountType;
+
+    @Column(name = "agent_saving_account_no", length = 50, nullable = false)
+    private String agentSavingAccountNo;
+
+    @Column(name = "agent_opening_date", nullable = false)
+    private LocalDate agentOpeningDate;
+
+    @Column(name = "agent_birth_date", nullable = false)
+    private LocalDate agentBirthDate;
+
+    @Column(name = "agent_current_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal agentCurrentBalance;
+
+    @Column(name = "agent_opening_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal agentOpeningBalance;
+
+    /**
+     * The branch this agent belongs to, and the thing of record for it.
+     *
+     * Defaults to the agent's client's office - where the person sits on the bank's books - but is
+     * chosen on the screen, since an agent can be registered at one branch and collect out of
+     * another.
+     */
+    @ManyToOne
+    @JoinColumn(name = "office_id")
+    private Office office;
+
+    /**
+     * The office's name, held alongside the office itself.
+     *
+     * Redundant by design: the batch job's branch filter and several reports match on this name, and
+     * were written before the office link existed. It is always written from {@link #office}, never
+     * on its own, so the two cannot drift apart.
+     */
+    @Column(name = "home_branch", length = 100)
+    private String homeBranch;
+
+    /**
+     * The ledger account this agent's collections pass through, if the bank has given them one.
+     *
+     * Collections debit it on their way to the customer and settlements credit it when the cash
+     * arrives, so what is left standing on it is what this agent is holding and has not brought in.
+     * One agent to an account - shared, it would say nothing that the old single account did not.
+     *
+     * Null for the agents that predate this, and they go on using the scheme's shared agent-cash
+     * account exactly as before. Nothing about the route the money takes depends on which of the
+     * two it is.
+     */
+    @ManyToOne
+    @JoinColumn(name = "gl_account_id")
+    private GLAccount glAccount;
+
+    /**
+     * Commission earned by Commission Calculation but not yet paid out. Commission Posting pays it and
+     * resets this to zero, so it reads as "owed to this agent right now" - which is what the legacy
+     * SubAgent Master screen's "Comm" box shows.
+     */
+    @Column(name = "commission", scale = 6, precision = 19, nullable = false)
+    private BigDecimal commission;
+
+    /** Whether Commission Calculation covers this agent at all ("Com. Calculation" on the legacy screen). */
+    @Column(name = "commission_calculation", nullable = false)
+    private boolean commissionCalculation;
+
+    /** TDS is withheld from commission at source when the bank has it switched on for this agent. */
+    @Column(name = "tds_applicable", nullable = false)
+    private boolean tdsApplicable;
+
+    @Column(name = "tds_percent", scale = 6, precision = 19, nullable = false)
+    private BigDecimal tdsPercent;
+
+    /** Running total of TDS withheld, the legacy screen's "TDS Amt". */
+    @Column(name = "tds_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal tdsAmount;
+
+    /** The four figures the Agent Commission Statement subtracts from gross commission. */
+    @Column(name = "deduct_commission", scale = 6, precision = 19, nullable = false)
+    private BigDecimal deductCommission;
+
+    @Column(name = "agent_deposit", scale = 6, precision = 19, nullable = false)
+    private BigDecimal agentDeposit;
+
+    @Column(name = "festival_advance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal festivalAdvance;
+
+    @Column(name = "other_deduction", scale = 6, precision = 19, nullable = false)
+    private BigDecimal otherDeduction;
+
+    @Column(name = "last_commission_date")
+    private LocalDate lastCommissionDate;
+
+    /**
+     * An agent who stops collecting is deactivated, never deleted: every party collection, settlement
+     * and commission posting is recorded against it, so removing it would orphan its whole history.
+     * An inactive agent stays out of the pick lists for new collection work while its record and
+     * history stay intact, and it can be switched back on.
+     */
+    @Column(name = "is_active", nullable = false)
+    private boolean active;
+
+    /**
+     * When the relationship ended, or null while the agent is on the books.
+     *
+     * Distinct from {@code active}: switching an agent off stops them collecting and has to be
+     * possible immediately, whereas closing is the end of the relationship and is only allowed once
+     * nothing is left hanging. A closed agent is never deleted - their whole collection history is
+     * recorded against them.
+     */
+    @Column(name = "close_date")
+    private LocalDate closeDate;
+
+    @OneToMany(mappedBy = "agent", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+    @OrderBy("id")
+    private List<AgentGuarantor> guarantors = new ArrayList<>();
+
+    protected Agent() {
+        //
+    }
+
+    private Agent(final Client client, final String agentCode, final String agentName, final String agentAddress1,
+            final String agentAddress2, final String agentCity, final String agentPinCode, final String agentTelephone,
+            final String agentSavingAccountType, final String agentSavingAccountNo, final LocalDate agentOpeningDate,
+            final LocalDate agentBirthDate, final BigDecimal agentOpeningBalance, final Office office) {
+        this.client = client;
+        this.agentCode = agentCode;
+        this.agentName = agentName;
+        this.agentAddress1 = agentAddress1;
+        this.agentAddress2 = StringUtils.defaultIfEmpty(agentAddress2, null);
+        this.agentCity = agentCity;
+        this.agentPinCode = agentPinCode;
+        this.agentTelephone = StringUtils.defaultIfEmpty(agentTelephone, null);
+        this.agentSavingAccountType = agentSavingAccountType;
+        this.agentSavingAccountNo = agentSavingAccountNo;
+        this.agentOpeningDate = agentOpeningDate;
+        this.agentBirthDate = agentBirthDate;
+        this.agentOpeningBalance = agentOpeningBalance == null ? BigDecimal.ZERO : agentOpeningBalance;
+        this.agentCurrentBalance = this.agentOpeningBalance;
+        setOffice(office);
+        this.active = true;
+
+        this.commission = BigDecimal.ZERO;
+        // Commission is earned unless someone says otherwise, matching the legacy screen's default.
+        this.commissionCalculation = true;
+        this.tdsApplicable = false;
+        this.tdsPercent = BigDecimal.ZERO;
+        this.tdsAmount = BigDecimal.ZERO;
+        this.deductCommission = BigDecimal.ZERO;
+        this.agentDeposit = BigDecimal.ZERO;
+        this.festivalAdvance = BigDecimal.ZERO;
+        this.otherDeduction = BigDecimal.ZERO;
+    }
+
+    /**
+     * @param office
+     *            the branch this agent belongs to, resolved by the caller from the command's
+     *            {@code officeId} or, failing that, from the client's own office.
+     */
+    public static Agent fromJson(final Client client, final String agentCode, final Office office, final JsonCommand command) {
+        final String agentName = command.stringValueOfParameterNamed("agentNameId");
+        final String agentAddress1 = command.stringValueOfParameterNamed("agentAddress1");
+        final String agentAddress2 = command.stringValueOfParameterNamedAllowingNull("agentAddress2");
+        final String agentCity = command.stringValueOfParameterNamed("agentCity");
+        final String agentPinCode = command.stringValueOfParameterNamed("agentPinCode");
+        final String agentTelephone = command.stringValueOfParameterNamedAllowingNull("agentTelephone");
+        final String agentSavingAccountType = command.stringValueOfParameterNamed("agentSavingAccountType");
+        final String agentSavingAccountNo = command.stringValueOfParameterNamed("agentSavingAccountNo");
+        final LocalDate agentOpeningDate = command.localDateValueOfParameterNamed("agentOpeningDate");
+        final LocalDate agentBirthDate = command.localDateValueOfParameterNamed("agentBirthDate");
+        final BigDecimal agentOpeningBalance = command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("agentOpeningBalance");
+
+        return new Agent(client, agentCode, agentName, agentAddress1, agentAddress2, agentCity, agentPinCode, agentTelephone,
+                agentSavingAccountType, agentSavingAccountNo, agentOpeningDate, agentBirthDate, agentOpeningBalance, office);
+    }
+
+    public void addGuarantor(final AgentGuarantor guarantor) {
+        guarantor.setAgent(this);
+        this.guarantors.add(guarantor);
+    }
+
+    public void resetGuarantors() {
+        this.guarantors.clear();
+    }
+
+    /**
+     * Commission Calculation: adds what this agent earned to the amount owed to them, withholds the
+     * TDS that went with it, and stamps the date commission is now calculated through - so the next
+     * Commission Calculation only covers collections since then, and re-running it for the same
+     * period finds nothing left to earn.
+     */
+    public void accrueCommission(final BigDecimal netAmount, final BigDecimal tdsWithheld, final LocalDate throughDate) {
+        this.commission = this.commission.add(netAmount);
+        this.tdsAmount = this.tdsAmount.add(tdsWithheld);
+        this.lastCommissionDate = throughDate;
+    }
+
+    /**
+     * Commission Posting: pays the given amount out of what is owed and returns what remains owed.
+     *
+     * The amount is the one the run previewed rather than whatever is owed at this moment, so what
+     * gets paid is always what was seen and approved. Since it comes off the owed figure, a second
+     * posting of the same commission finds nothing left to pay.
+     */
+    public BigDecimal payOutCommission(final BigDecimal amount) {
+        this.commission = this.commission.subtract(amount);
+        return this.commission;
+    }
+
+    /**
+     * Charges the agent for an account of theirs that was closed before its term was up.
+     *
+     * Booked against {@code deductCommission} rather than taken straight off {@code commission},
+     * because what is owed at this moment may be nothing - commission is paid out in runs, and an
+     * agent who was paid yesterday would otherwise escape the charge entirely. Held as a deduction it
+     * is carried until there is commission to take it from, and it shows on the Agent Commission
+     * Statement between gross and take-home, where an agent can see what was charged and why.
+     */
+    public BigDecimal chargePrematureClosure(final BigDecimal amount) {
+        if (amount == null || amount.compareTo(BigDecimal.ZERO) <= 0) {
+            return this.deductCommission;
+        }
+        this.deductCommission = this.deductCommission.add(amount);
+        return this.deductCommission;
+    }
+
+    /**
+     * The four figures the Agent Commission Statement subtracts between gross commission and the
+     * agent's take-home total. They are standing amounts on the agent, not per-run ones, so a run
+     * deducts whatever they hold when it is calculated.
+     */
+    public BigDecimal totalDeductions() {
+        return this.deductCommission.add(this.agentDeposit).add(this.festivalAdvance).add(this.otherDeduction);
+    }
+
+    public boolean isClosed() {
+        return this.closeDate != null;
+    }
+
+    /** Cash collected from customers that has not yet reached a branch. */
+    public boolean holdsCash() {
+        return this.agentCurrentBalance.compareTo(BigDecimal.ZERO) != 0;
+    }
+
+    /** Commission earned but not yet paid out. */
+    public boolean isOwedCommission() {
+        return this.commission.compareTo(BigDecimal.ZERO) != 0;
+    }
+
+    /**
+     * Ends the relationship. The caller checks first that no accounts are still assigned; the two
+     * money conditions are checked here, where the figures live.
+     *
+     * Closing also switches the agent off, since an agent who is no longer on the books cannot be
+     * collecting either.
+     */
+    public void close(final LocalDate closeDate) {
+        this.closeDate = closeDate;
+        this.active = false;
+    }
+
+    /**
+     * Cash this agent has collected from parties but not yet handed over to a branch (an Agent Tran
+     * settlement). Raised by a Party Tran collection, lowered by an Agent Tran settlement.
+     */
+    public BigDecimal credit(final BigDecimal amount) {
+        this.agentCurrentBalance = this.agentCurrentBalance.add(amount);
+        return this.agentCurrentBalance;
+    }
+
+    public BigDecimal settle(final BigDecimal amount) {
+        this.agentCurrentBalance = this.agentCurrentBalance.subtract(amount);
+        return this.agentCurrentBalance;
+    }
+
+    public void changeClient(final Client newClient) {
+        this.client = newClient;
+    }
+
+    /**
+     * Moves the agent to a branch, writing the office's name into {@code homeBranch} in the same
+     * step so the name never has to be set by hand and never lags behind the office.
+     */
+    public void setOffice(final Office office) {
+        this.office = office;
+        this.homeBranch = office == null ? null : StringUtils.defaultIfEmpty(office.getName(), null);
+    }
+
+    public Long officeId() {
+        return this.office == null ? null : this.office.getId();
+    }
+
+    /**
+     * Points this agent's collections at a ledger account, or back at the scheme's shared one.
+     *
+     * Whether the account may be used at all - that it exists, is an asset account, is not disabled,
+     * and is not already another agent's - is settled before this is called. By the time the agent
+     * holds it, the question is closed.
+     */
+    public void setGlAccount(final GLAccount glAccount) {
+        this.glAccount = glAccount;
+    }
+
+    public Long glAccountId() {
+        return this.glAccount == null ? null : this.glAccount.getId();
+    }
+
+    public Long clientId() {
+        return this.client.getId();
+    }
+
+    public Map<String, Object> update(final JsonCommand command) {
+
+        final Map<String, Object> actualChanges = new LinkedHashMap<>(10);
+
+        if (command.isChangeInLongParameterNamed("clientId", this.client.getId())) {
+            actualChanges.put("clientId", command.longValueOfParameterNamed("clientId"));
+        }
+
+        if (command.isChangeInStringParameterNamed("agentNameId", this.agentName)) {
+            final String newValue = command.stringValueOfParameterNamed("agentNameId");
+            actualChanges.put("agentNameId", newValue);
+            this.agentName = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentAddress1", this.agentAddress1)) {
+            final String newValue = command.stringValueOfParameterNamed("agentAddress1");
+            actualChanges.put("agentAddress1", newValue);
+            this.agentAddress1 = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentAddress2", this.agentAddress2)) {
+            final String newValue = command.stringValueOfParameterNamed("agentAddress2");
+            actualChanges.put("agentAddress2", newValue);
+            this.agentAddress2 = StringUtils.defaultIfEmpty(newValue, null);
+        }
+
+        if (command.isChangeInStringParameterNamed("agentCity", this.agentCity)) {
+            final String newValue = command.stringValueOfParameterNamed("agentCity");
+            actualChanges.put("agentCity", newValue);
+            this.agentCity = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentPinCode", this.agentPinCode)) {
+            final String newValue = command.stringValueOfParameterNamed("agentPinCode");
+            actualChanges.put("agentPinCode", newValue);
+            this.agentPinCode = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentTelephone", this.agentTelephone)) {
+            final String newValue = command.stringValueOfParameterNamed("agentTelephone");
+            actualChanges.put("agentTelephone", newValue);
+            this.agentTelephone = StringUtils.defaultIfEmpty(newValue, null);
+        }
+
+        if (command.isChangeInStringParameterNamed("agentSavingAccountType", this.agentSavingAccountType)) {
+            final String newValue = command.stringValueOfParameterNamed("agentSavingAccountType");
+            actualChanges.put("agentSavingAccountType", newValue);
+            this.agentSavingAccountType = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("agentSavingAccountNo", this.agentSavingAccountNo)) {
+            final String newValue = command.stringValueOfParameterNamed("agentSavingAccountNo");
+            actualChanges.put("agentSavingAccountNo", newValue);
+            this.agentSavingAccountNo = newValue;
+        }
+
+        if (command.isChangeInDateParameterNamed("agentOpeningDate", this.agentOpeningDate)) {
+            actualChanges.put("agentOpeningDate", command.stringValueOfParameterNamed("agentOpeningDate"));
+            this.agentOpeningDate = command.localDateValueOfParameterNamed("agentOpeningDate");
+        }
+
+        if (command.isChangeInDateParameterNamed("agentBirthDate", this.agentBirthDate)) {
+            actualChanges.put("agentBirthDate", command.stringValueOfParameterNamed("agentBirthDate"));
+            this.agentBirthDate = command.localDateValueOfParameterNamed("agentBirthDate");
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("agentOpeningBalance", this.agentOpeningBalance)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("agentOpeningBalance");
+            actualChanges.put("agentOpeningBalance", newValue);
+            // The current balance is the opening balance plus collections less settlements, so
+            // correcting the opening figure has to move the current one by the same amount.
+            // Setting it alone would leave the two contradicting each other for good, since nothing
+            // else ever recomputes the current balance from scratch.
+            this.agentCurrentBalance = this.agentCurrentBalance.add(newValue.subtract(this.agentOpeningBalance));
+            this.agentOpeningBalance = newValue;
+            actualChanges.put("agentCurrentBalance", this.agentCurrentBalance);
+        }
+
+        if (command.isChangeInBooleanParameterNamed("active", this.active)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("active");
+            actualChanges.put("active", newValue);
+            this.active = newValue;
+        }
+
+        // Commission settings and the standing deductions. The running totals the batch maintains -
+        // `commission` and `tdsAmount` - are deliberately not editable here: they are the outcome of
+        // posted runs, and typing over them would put the agent's balance out of step with the runs
+        // that produced it.
+        if (command.isChangeInBooleanParameterNamed("commissionCalculation", this.commissionCalculation)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("commissionCalculation");
+            actualChanges.put("commissionCalculation", newValue);
+            this.commissionCalculation = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("tdsApplicable", this.tdsApplicable)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("tdsApplicable");
+            actualChanges.put("tdsApplicable", newValue);
+            this.tdsApplicable = newValue;
+        }
+
+        decimalChange(command, actualChanges, "tdsPercent", this.tdsPercent, v -> this.tdsPercent = v);
+        decimalChange(command, actualChanges, "deductCommission", this.deductCommission, v -> this.deductCommission = v);
+        decimalChange(command, actualChanges, "agentDeposit", this.agentDeposit, v -> this.agentDeposit = v);
+        decimalChange(command, actualChanges, "festivalAdvance", this.festivalAdvance, v -> this.festivalAdvance = v);
+        decimalChange(command, actualChanges, "otherDeduction", this.otherDeduction, v -> this.otherDeduction = v);
+
+        // A rate means nothing while TDS is switched off, so it is not left behind to be applied by a
+        // later switch-on nobody connected to it.
+        if (!this.tdsApplicable) {
+            this.tdsPercent = BigDecimal.ZERO;
+        }
+
+        return actualChanges;
+    }
+
+    private void decimalChange(final JsonCommand command, final Map<String, Object> actualChanges, final String paramName,
+            final BigDecimal existingValue, final Consumer<BigDecimal> setter) {
+        if (command.isChangeInBigDecimalParameterNamed(paramName, existingValue)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed(paramName);
+            actualChanges.put(paramName, newValue);
+            setter.accept(newValue == null ? BigDecimal.ZERO : newValue);
+        }
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/domain/AgentGuarantor.java

@@ -0,0 +1,87 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+
+/**
+ * A single guarantor recorded against an {@link Agent} (or, reused with the same shape, against a
+ * SubAgent). Always created/replaced as part of its parent agent's own create/update command - it has
+ * no independent API of its own.
+ *
+ * Audited in its own right even so: a guarantor is who the bank goes to if an agent's collections go
+ * missing, and a timestamp on the agent saying something changed does not say that the person
+ * standing behind them was swapped, nor by whom.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_agent_guarantor")
+public class AgentGuarantor extends AbstractAuditableCustom {
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    @Column(name = "client_id", nullable = false)
+    private Long clientId;
+
+    @Column(name = "guarantor_name", length = 100, nullable = false)
+    private String guarantorName;
+
+    @Column(name = "address1", length = 200, nullable = false)
+    private String address1;
+
+    @Column(name = "address2", length = 200)
+    private String address2;
+
+    @Column(name = "city", length = 100, nullable = false)
+    private String city;
+
+    @Column(name = "pin_code", length = 20, nullable = false)
+    private String pinCode;
+
+    @Column(name = "telephone", length = 20)
+    private String telephone;
+
+    protected AgentGuarantor() {
+        //
+    }
+
+    public AgentGuarantor(final Long clientId, final String guarantorName, final String address1, final String address2,
+            final String city, final String pinCode, final String telephone) {
+        this.clientId = clientId;
+        this.guarantorName = guarantorName;
+        this.address1 = address1;
+        this.address2 = StringUtils.defaultIfEmpty(address2, null);
+        this.city = city;
+        this.pinCode = pinCode;
+        this.telephone = StringUtils.defaultIfEmpty(telephone, null);
+    }
+
+    void setAgent(final Agent agent) {
+        this.agent = agent;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentCannotBeClosedException.java

@@ -0,0 +1,39 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an agent is closed while their books are not square.
+ *
+ * Closing is the end of the relationship, so it is refused until nothing is left hanging: no accounts
+ * still being collected from, no cash held that has not reached a branch, and no commission earned but
+ * unpaid. Each of those is money or a customer that would be left with no one responsible for it.
+ *
+ * Deactivating is deliberately not guarded this way. Switching an agent off has to be possible the
+ * moment the bank decides it - if it waited for the books to be squared, an agent the bank wanted
+ * stopped would keep collecting while the paperwork caught up.
+ */
+public class AgentCannotBeClosedException extends AbstractPlatformDomainRuleException {
+
+    public AgentCannotBeClosedException(final String agentCode, final String reason) {
+        super("error.msg.dds.agent.cannot.be.closed", "Agent " + agentCode + " cannot be closed: " + reason, agentCode, reason);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentCannotGuaranteeItselfException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an agent is listed as one of its own guarantors - a guarantee is only worth something
+ * coming from someone other than the agent it backs.
+ */
+public class AgentCannotGuaranteeItselfException extends AbstractPlatformDomainRuleException {
+
+    public AgentCannotGuaranteeItselfException(final Long clientId) {
+        super("error.msg.agent.cannot.guarantee.itself", "An agent cannot be its own guarantor", clientId);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentCommissionAccountUnusableException.java

@@ -0,0 +1,37 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a commission run cannot pay an agent because their account will not take the credit.
+ *
+ * The account is checked when it is chosen, so reaching this means something changed afterwards -
+ * most likely the account was closed. Failing here rolls the whole run back rather than paying the
+ * other agents and leaving this one silently unpaid: a commission run that has half happened is
+ * worse to unpick than one that has not happened at all.
+ */
+public class AgentCommissionAccountUnusableException extends AbstractPlatformDomainRuleException {
+
+    public AgentCommissionAccountUnusableException(final String agentCode, final String reason) {
+        super("error.msg.dds.agent.commission.account.unusable",
+                "Commission for agent " + agentCode + " could not be paid: " + reason + ".", agentCode, reason);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentGlAccountUnusableException.java

@@ -0,0 +1,38 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when the ledger account named for an agent could not carry that agent's cash.
+ *
+ * Refused when it is chosen rather than when it is first posted to. An account that cannot take the
+ * entry fails the whole collection, at the counter, with a customer waiting - and the person who
+ * picked it is not the person who finds out.
+ */
+public class AgentGlAccountUnusableException extends AbstractPlatformDomainRuleException {
+
+    public AgentGlAccountUnusableException(final String glCode, final String reason) {
+        super("error.msg.dds.agent.gl.account.unusable",
+                "Ledger account " + glCode + " cannot be used for this agent: " + reason
+                        + ". Choose a detail asset account that no other agent already holds.",
+                glCode, reason);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentNotFoundException.java

@@ -0,0 +1,40 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+import org.springframework.dao.EmptyResultDataAccessException;
+
+/**
+ * A {@link RuntimeException} thrown when a DDS agent resource is not found.
+ */
+public class AgentNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public AgentNotFoundException(final Long id) {
+        super("error.msg.agent.id.invalid", "Agent with identifier " + id + " does not exist", id);
+    }
+
+    public AgentNotFoundException(final Long id, final EmptyResultDataAccessException e) {
+        super("error.msg.agent.id.invalid", "Agent with identifier " + id + " does not exist", id, e);
+    }
+
+    public AgentNotFoundException(final String agentCode) {
+        super("error.msg.agent.code.invalid", "Agent with code " + agentCode + " does not exist", agentCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentSavingsAccountClientMismatchException.java

@@ -0,0 +1,38 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an agent is given a savings account that belongs to somebody else.
+ *
+ * An agent's commission is their own earnings, so it is paid into their own account. Accepting
+ * another person's account number here would route one person's pay into another's balance - a
+ * mistake that reads as ordinary data entry and would only surface when the person who should have
+ * been paid asked where their money went.
+ */
+public class AgentSavingsAccountClientMismatchException extends AbstractPlatformDomainRuleException {
+
+    public AgentSavingsAccountClientMismatchException(final String accountNo) {
+        super("error.msg.dds.agent.savings.account.client.mismatch",
+                "Savings account " + accountNo + " belongs to a different client. An agent's commission is paid into their own account.",
+                accountNo);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentSavingsAccountNotFoundException.java

@@ -0,0 +1,36 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an agent is given a savings account number that no open account carries.
+ *
+ * The agent's commission is paid into this account, so a number that exists only as typed text means
+ * a payment with nowhere to land - and nothing downstream would catch it, because the commission run
+ * records what it paid, not whether the account it named was real.
+ */
+public class AgentSavingsAccountNotFoundException extends AbstractPlatformDomainRuleException {
+
+    public AgentSavingsAccountNotFoundException(final String accountNo) {
+        super("error.msg.dds.agent.savings.account.not.found",
+                "No open savings account has the number " + accountNo + ". Pick one of the client's own accounts.", accountNo);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/agent/exception/AgentSavingsAccountNotOperativeException.java

@@ -0,0 +1,41 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an agent's commission account is a fixed or recurring deposit rather than a savings
+ * account.
+ *
+ * Commission is paid in as a credit whenever a commission run posts. A savings account takes credits
+ * at any time; a fixed deposit is a single sum placed for a term, and a recurring deposit takes only
+ * its own scheduled instalments - so paying into either is not a thing a bank does, and the posting
+ * would fail when the run came round. Refusing it as the account is chosen puts the error in front
+ * of the officer who can fix it, rather than in a batch log weeks later.
+ */
+public class AgentSavingsAccountNotOperativeException extends AbstractPlatformDomainRuleException {
+
+    public AgentSavingsAccountNotOperativeException(final String accountNo, final String accountKind) {
+        super("error.msg.dds.agent.savings.account.not.operative",
+                "Account " + accountNo + " is a " + accountKind + " account. Commission has to be paid into an ordinary savings "
+                        + "account, so pick one of the client's own - not a deposit and not a DDS scheme account.",
+                accountNo, accountKind);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/commissionslab/data/CommissionSlabData.java

@@ -0,0 +1,39 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.commissionslab.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+public final class CommissionSlabData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final String slabType;
+    private final BigDecimal slabFrom;
+    private final BigDecimal slabTo;
+    private final BigDecimal commissionPercent;
+}

fineract-core/src/main/java/org/apache/fineract/organisation/commissionslab/domain/CommissionSlab.java

@@ -0,0 +1,98 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.commissionslab.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+
+/**
+ * One row of the agent commission chart: an ACCOUNT slab (commission percentage on collection
+ * volume) or a COMMISSION slab (the override a senior agent earns on a sub-agent's commission).
+ * Reference data, not history: a slab says what an agent earns on a given collection volume, and the
+ * commission run reads whatever the chart says at the time it runs. A mistyped range or percentage
+ * therefore has to be correctable - the legacy screen offered an edit on every saved row - so a slab
+ * can be updated. It still cannot be deleted: removing a range silently pays nothing to any agent who
+ * lands in it, which reads as a system fault rather than a decision.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_commission_slab")
+public class CommissionSlab extends AbstractAuditableCustom {
+
+    @Column(name = "slab_type", length = 20, nullable = false)
+    private String slabType;
+
+    @Column(name = "slab_from", scale = 6, precision = 19, nullable = false)
+    private BigDecimal slabFrom;
+
+    @Column(name = "slab_to", scale = 6, precision = 19, nullable = false)
+    private BigDecimal slabTo;
+
+    @Column(name = "commission_percent", scale = 6, precision = 19, nullable = false)
+    private BigDecimal commissionPercent;
+
+    protected CommissionSlab() {
+        //
+    }
+
+    public CommissionSlab(final String slabType, final BigDecimal slabFrom, final BigDecimal slabTo, final BigDecimal commissionPercent) {
+        this.slabType = slabType;
+        this.slabFrom = slabFrom;
+        this.slabTo = slabTo;
+        this.commissionPercent = commissionPercent;
+    }
+
+    /**
+     * Corrects this slab, reporting only what actually changed so the audit trail records the
+     * correction rather than a wholesale rewrite.
+     */
+    public Map<String, Object> update(final JsonCommand command) {
+        final Map<String, Object> actualChanges = new LinkedHashMap<>(4);
+
+        if (command.isChangeInStringParameterNamed("slabType", this.slabType)) {
+            final String newValue = command.stringValueOfParameterNamed("slabType");
+            actualChanges.put("slabType", newValue);
+            this.slabType = newValue;
+        }
+        if (command.isChangeInBigDecimalParameterNamed("slabFrom", this.slabFrom)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("slabFrom");
+            actualChanges.put("slabFrom", newValue);
+            this.slabFrom = newValue;
+        }
+        if (command.isChangeInBigDecimalParameterNamed("slabTo", this.slabTo)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("slabTo");
+            actualChanges.put("slabTo", newValue);
+            this.slabTo = newValue;
+        }
+        if (command.isChangeInBigDecimalParameterNamed("commissionPercent", this.commissionPercent)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("commissionPercent");
+            actualChanges.put("commissionPercent", newValue);
+            this.commissionPercent = newValue;
+        }
+
+        return actualChanges;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/commissionslab/exception/CommissionSlabNotFoundException.java

@@ -0,0 +1,31 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.commissionslab.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+
+/**
+ * Thrown when a commission slab being corrected no longer exists.
+ */
+public class CommissionSlabNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public CommissionSlabNotFoundException(final Long slabId) {
+        super("error.msg.commissionslab.id.invalid", "Commission slab with identifier " + slabId + " does not exist", slabId);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/commissionslab/exception/OverlappingCommissionSlabException.java

@@ -0,0 +1,42 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.commissionslab.exception;
+
+import java.math.BigDecimal;
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a commission slab's range overlaps one that already covers part of it.
+ *
+ * The commission run picks the first slab whose range contains the agent's collection volume, so
+ * two slabs covering the same figure make the rate that gets applied a matter of which row the
+ * database returns first. The same agent could be paid a different percentage from one month to the
+ * next with nothing in the data to explain it, which is why this is refused rather than warned
+ * about.
+ */
+public class OverlappingCommissionSlabException extends AbstractPlatformDomainRuleException {
+
+    public OverlappingCommissionSlabException(final String slabType, final BigDecimal from, final BigDecimal to,
+            final BigDecimal existingFrom, final BigDecimal existingTo) {
+        super("error.msg.commissionslab.overlapping",
+                slabType + " slab " + from.toPlainString() + " to " + to.toPlainString() + " overlaps the existing slab "
+                        + existingFrom.toPlainString() + " to " + existingTo.toPlainString(),
+                slabType, from, to, existingFrom, existingTo);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/organisation/office/domain/OfficeRepositoryWrapper.java

@@ -61,4 +61,15 @@ public class OfficeRepositoryWrapper {
     public void delete(final Office entity) {
         this.repository.delete(entity);
     }
+
+    /**
+     * Deletes and flushes in the same call, so a foreign-key violation the caller did not already check
+     * for (a savings transaction, a GL journal entry, a teller position -- anything on m_office's long
+     * tail of referencing tables) surfaces synchronously here, inside the caller's own try/catch, rather
+     * than at transaction-commit time where it can no longer be turned into a clean error message.
+     */
+    public void deleteAndFlush(final Office entity) {
+        this.repository.delete(entity);
+        this.repository.flush();
+    }
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlert.java

@@ -78,6 +78,30 @@ public class AmlAlert extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "disposition", length = 20)
     private String disposition;
 
+    /**
+     * The other rules this same transaction matched, comma-separated.
+     *
+     * <p>
+     * One transaction raises one alert, under the rule that most warrants attention - otherwise a
+     * single deposit arrives as several alerts and an officer has to dispose of each, with nothing
+     * stopping them clearing one while escalating another. The rules that did not win are kept here
+     * so the case file still shows everything that fired.
+     */
+    @Column(name = "also_matched_rules", length = 500)
+    private String alsoMatchedRules;
+
+    /**
+     * The worst severity band across every rule this transaction matched — 1 Low, 2 Medium, 3 High.
+     *
+     * <p>
+     * Not the same as the governing rule's own severity. A statutory CTR outranks everything when
+     * the alert is raised, so a high-severity rule can end up recorded in {@link #alsoMatchedRules}
+     * and vanish from the screen. An officer disposing of low and medium alerts in a batch would
+     * then be handed a transaction that had tripped a high-severity rule with nothing to show it.
+     */
+    @Column(name = "highest_severity")
+    private Integer highestSeverity;
+
     protected AmlAlert() {}
 
     public static AmlAlert raise(AmlTransactionType transactionType, Long transactionId, Client client, AmlTransactionRule rule,
@@ -94,6 +118,58 @@ public class AmlAlert extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         return alert;
     }
 
+    public String getAlsoMatchedRules() {
+        return this.alsoMatchedRules;
+    }
+
+    public Integer getHighestSeverity() {
+        return this.highestSeverity;
+    }
+
+    public void recordHighestSeverity(final Integer severity) {
+        this.highestSeverity = severity;
+    }
+
+    /** Truncated to the column width: the record is a convenience, never a reason to fail a save. */
+    public void recordAlsoMatchedRules(final String ruleCodes) {
+        this.alsoMatchedRules = ruleCodes == null || ruleCodes.isBlank() ? null
+                : (ruleCodes.length() > 500 ? ruleCodes.substring(0, 500) : ruleCodes);
+    }
+
+    /**
+     * Whether this alert is being worked by somebody other than the given officer.
+     *
+     * <p>
+     * An alert under review belongs to whoever opened it until they decide it or hand it back. A second officer
+     * reading the same case and reaching their own verdict is the failure this exists to prevent: the transaction
+     * would carry two reviews, and whichever was written last would be the one on file.
+     */
+    public boolean isHeldByAnother(final AppUser officer) {
+        return AmlAlertStatus.UNDER_REVIEW.name().equals(this.status) && this.reviewedBy != null && officer != null
+                && !this.reviewedBy.getId().equals(officer.getId());
+    }
+
+    /**
+     * Brings the alert into line with the Principal Officer's conclusion on the case it opened.
+     *
+     * <p>
+     * An escalation is a referral, not a verdict: it says the AML Officer wanted the case looked at. The verdict is
+     * the Principal Officer's, and when they conclude the case clear the alert has to say so too. Left as ESCALATED,
+     * the feed would go on showing a transaction as suspicious after the bank had decided it was not - and the officer
+     * who cleared it would have no way to see their own conclusion reflected where the alert is worked.
+     *
+     * <p>
+     * Distinct from {@link #whitelist}: this does not pass the alert's own immutability guard, because it is not a
+     * second officer overturning a decision. It is the case this alert was referred into, coming back with its answer.
+     */
+    public void applyStrConclusion(final boolean suspicious, final AppUser principalOfficer, final String notes) {
+        this.reviewedBy = principalOfficer;
+        this.reviewedOn = LocalDateTime.now();
+        this.reviewNotes = notes;
+        this.disposition = (suspicious ? AmlAlertDisposition.ESCALATE : AmlAlertDisposition.WHITELIST).name();
+        this.status = (suspicious ? AmlAlertStatus.ESCALATED : AmlAlertStatus.WHITELISTED).name();
+    }
+
     public void whitelist(AppUser reviewer, String notes) {
         this.reviewedBy = reviewer;
         this.reviewedOn = LocalDateTime.now();

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlertRepository.java

@@ -44,4 +44,18 @@ public interface AmlAlertRepository extends JpaRepository<AmlAlert, Long> {
      * twice, which would put two STR cases in front of the Principal Officer for a single transaction.
      */
     List<AmlAlert> findByRule_IdAndTransactionId(Long ruleId, Long transactionId);
+
+    /**
+     * A customer's still-open alerts inside the observation window, oldest first.
+     *
+     * <p>
+     * What a recurring-behaviour review acts on. Open is defined as not yet decided rather than by naming the statuses
+     * that are open, so a status this query does not know about is still treated as work: an alert wrongly included
+     * costs a reviewer a glance, one wrongly excluded is a pattern the bank never looked at. A decision about the
+     * customer's pattern must not reopen alerts an officer has already disposed of individually - and oldest first so
+     * that a partial failure leaves the longest-standing ones dealt with.
+     */
+    @Query("SELECT a FROM AmlAlert a WHERE a.client.id = :clientId AND a.raisedOn >= :since "
+            + "AND a.status NOT IN ('WHITELISTED', 'ESCALATED') ORDER BY a.raisedOn ASC")
+    List<AmlAlert> findOpenAlertsForClientSince(@Param("clientId") Long clientId, @Param("since") LocalDateTime since);
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlertRule.java

@@ -0,0 +1,163 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+import org.apache.fineract.useradministration.domain.AppUser;
+
+/**
+ * One rule a transaction matched, and what the officer decided about that rule.
+ *
+ * <p>
+ * The alert is the case; this is a finding within it. A single deposit can trip six rules where five are explained by
+ * the customer's declared business and the sixth is not - one verdict over the whole alert either loses that sixth
+ * observation or sends the other five to an STR they do not belong in.
+ *
+ * <p>
+ * The rule is held by code rather than by a foreign key to {@link AmlTransactionRule}, and the severity is copied in
+ * rather than read back through it. An alert records what was detected at the time; re-banding or retiring a rule
+ * afterwards must not rewrite what the officer was looking at when they decided.
+ */
+@Entity
+@Table(name = "m_aml_alert_rule")
+public class AmlAlertRule {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne
+    @JoinColumn(name = "alert_id", nullable = false)
+    private AmlAlert alert;
+
+    @Column(name = "rule_code", nullable = false, length = 100)
+    private String ruleCode;
+
+    @Column(name = "risk_category")
+    private Integer riskCategory;
+
+    @Column(name = "is_governing", nullable = false)
+    private boolean governing;
+
+    @Column(name = "disposition", length = 20)
+    private String disposition;
+
+    @ManyToOne
+    @JoinColumn(name = "reviewed_by")
+    private AppUser reviewedBy;
+
+    @Column(name = "reviewed_on")
+    private LocalDateTime reviewedOn;
+
+    @Column(name = "review_notes", length = 1000)
+    private String reviewNotes;
+
+    /**
+     * Whether the officer named this rule, as against it being closed to keep the case consistent.
+     *
+     * <p>
+     * Marking one rule suspicious escalates the transaction and closes every other rule under the same escalation -
+     * nothing may stay open behind a filed STR. Without this the record would read as though all of them had been
+     * examined and condemned, and on a transaction that tripped six rules, which one the officer put their name to is
+     * the substance of the finding.
+     */
+    @Column(name = "directly_decided", nullable = false)
+    private boolean directlyDecided;
+
+    protected AmlAlertRule() {}
+
+    public static AmlAlertRule of(final AmlAlert alert, final String ruleCode, final Integer riskCategory,
+            final boolean governing) {
+        final AmlAlertRule finding = new AmlAlertRule();
+        finding.alert = alert;
+        finding.ruleCode = ruleCode;
+        finding.riskCategory = riskCategory;
+        finding.governing = governing;
+        return finding;
+    }
+
+    /**
+     * @param directlyDecided
+     *            true when the officer named this rule; false when it was closed alongside one they named
+     */
+    public void decide(final AmlAlertDisposition disposition, final AppUser reviewer, final String notes,
+            final boolean directlyDecided) {
+        this.disposition = disposition.name();
+        this.reviewedBy = reviewer;
+        this.reviewedOn = LocalDateTime.now();
+        this.reviewNotes = notes;
+        this.directlyDecided = directlyDecided;
+    }
+
+    public boolean isDirectlyDecided() {
+        return this.directlyDecided;
+    }
+
+    public boolean isDecided() {
+        return this.disposition != null;
+    }
+
+    public boolean isEscalated() {
+        return AmlAlertDisposition.ESCALATE.name().equals(this.disposition);
+    }
+
+    public Long getId() {
+        return this.id;
+    }
+
+    public AmlAlert getAlert() {
+        return this.alert;
+    }
+
+    public String getRuleCode() {
+        return this.ruleCode;
+    }
+
+    public Integer getRiskCategory() {
+        return this.riskCategory;
+    }
+
+    public boolean isGoverning() {
+        return this.governing;
+    }
+
+    public String getDisposition() {
+        return this.disposition;
+    }
+
+    public AppUser getReviewedBy() {
+        return this.reviewedBy;
+    }
+
+    public LocalDateTime getReviewedOn() {
+        return this.reviewedOn;
+    }
+
+    public String getReviewNotes() {
+        return this.reviewNotes;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlAlertRuleRepository.java

@@ -0,0 +1,31 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.util.Collection;
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AmlAlertRuleRepository extends JpaRepository<AmlAlertRule, Long> {
+
+    List<AmlAlertRule> findByAlertId(Long alertId);
+
+    /** Every finding across a page of alerts, in one read rather than one query per alert. */
+    List<AmlAlertRule> findByAlertIdIn(Collection<Long> alertIds);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlRecurringEscalationTier.java

@@ -0,0 +1,106 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+/**
+ * How far a customer's repetition has gone, and what the bank's answer to it has to be.
+ *
+ * <p>
+ * A customer who surfaces once is a question; one who surfaces for the fortieth time is an answer the bank has not
+ * acted on. Without a ladder every review looked the same - same screen, same three buttons, same outcome - so the
+ * fortieth review cost an officer the same effort as the first and changed as little.
+ *
+ * <p>
+ * Each tier does two things: it sets how long a review holds the customer out of the queue, and it says what the
+ * reviewer is expected to do. The windows shorten as the tier rises, because a customer the bank is more worried
+ * about should come back sooner, not later.
+ */
+public enum AmlRecurringEscalationTier {
+
+    /** Ordinary repetition. A review stands for a quarter unless the count climbs into the next tier. */
+    ROUTINE(0, 90),
+
+    /**
+     * Enough repetition that the customer's risk rating is no longer just a KYC-time judgement. Reviewed monthly, and
+     * the reviewer is asked to consider whether the rating still fits.
+     */
+    ELEVATED(7, 30),
+
+    /**
+     * Beyond what a branch officer should be closing on their own. Reviewed fortnightly, and the review is expected
+     * to be taken by someone senior.
+     */
+    SENIOR(15, 14),
+
+    /**
+     * Repetition at a level that is itself the suspicion. An STR is the expected outcome, and clearing at this tier
+     * is a decision that has to be defensible on its own - so the review stands for a week only.
+     */
+    MANDATORY_STR(30, 7);
+
+    private final int minimumAlertCount;
+    private final int reviewValidityDays;
+
+    AmlRecurringEscalationTier(final int minimumAlertCount, final int reviewValidityDays) {
+        this.minimumAlertCount = minimumAlertCount;
+        this.reviewValidityDays = reviewValidityDays;
+    }
+
+    /** The tier a customer sitting on this many alerts falls into. */
+    public static AmlRecurringEscalationTier forAlertCount(final int alertCount) {
+        AmlRecurringEscalationTier tier = ROUTINE;
+        for (final AmlRecurringEscalationTier candidate : values()) {
+            if (alertCount >= candidate.minimumAlertCount) {
+                tier = candidate;
+            }
+        }
+        return tier;
+    }
+
+    public int getMinimumAlertCount() {
+        return minimumAlertCount;
+    }
+
+    public int getReviewValidityDays() {
+        return reviewValidityDays;
+    }
+
+    /**
+     * How far the alert count may climb before a standing review is set aside and the customer returns early.
+     *
+     * <p>
+     * A validity window alone would hold a customer out while their behaviour changed underneath it: reviewed at four
+     * alerts and then trips forty more the same week, the review would still stand for the full quarter. Allowing the
+     * count to grow by the tier's own span before forcing a return keeps ordinary repetition quiet while letting a
+     * genuine change in behaviour break through. Tighter at the higher tiers, where less change should be tolerated.
+     */
+    public int alertGrowthBeforeEarlyReturn() {
+        return switch (this) {
+            case ROUTINE -> 5;
+            case ELEVATED -> 4;
+            case SENIOR -> 3;
+            case MANDATORY_STR -> 2;
+        };
+    }
+
+    /** Whether a review at this tier is expected to raise an STR rather than close the customer off. */
+    public boolean expectsStr() {
+        return this == MANDATORY_STR;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlRecurringReview.java

@@ -26,6 +26,7 @@ import jakarta.persistence.Id;
 import jakarta.persistence.JoinColumn;
 import jakarta.persistence.ManyToOne;
 import jakarta.persistence.Table;
+import java.time.LocalDate;
 import java.time.LocalDateTime;
 import org.apache.fineract.portfolio.client.domain.Client;
 import org.apache.fineract.useradministration.domain.AppUser;
@@ -65,6 +66,20 @@ public class AmlRecurringReview {
     @Column(name = "reviewed_on", nullable = false)
     private LocalDateTime reviewedOn;
 
+    /**
+     * The date this review stops standing. Null on reviews taken before validity existed, which keep the older
+     * behaviour of lapsing the moment one more alert lands.
+     */
+    @Column(name = "valid_until")
+    private LocalDate validUntil;
+
+    @Column(name = "escalation_tier", length = 20)
+    private String escalationTier;
+
+    /** How many of the customer's open alerts this review actually disposed of. */
+    @Column(name = "alerts_actioned")
+    private Integer alertsActioned;
+
     protected AmlRecurringReview() {}
 
     public static AmlRecurringReview record(final Client client, final int alertCountAtReview,
@@ -76,9 +91,22 @@ public class AmlRecurringReview {
         review.notes = notes;
         review.reviewedBy = reviewedBy;
         review.reviewedOn = LocalDateTime.now();
+
+        // The tier follows from the count, not from what the reviewer picked: how often a customer has surfaced is a
+        // fact about them, and letting the outcome set it would let a customer be held at ROUTINE indefinitely by
+        // always being cleared.
+        final AmlRecurringEscalationTier tier = AmlRecurringEscalationTier.forAlertCount(alertCountAtReview);
+        review.escalationTier = tier.name();
+        review.validUntil = LocalDate.now().plusDays(tier.getReviewValidityDays());
+        review.alertsActioned = 0;
         return review;
     }
 
+    /** Records how many open alerts the review disposed of, once the caller has acted on them. */
+    public void recordAlertsActioned(final int count) {
+        this.alertsActioned = count;
+    }
+
     public Long getId() {
         return id;
     }
@@ -106,4 +134,35 @@ public class AmlRecurringReview {
     public LocalDateTime getReviewedOn() {
         return reviewedOn;
     }
+
+    public LocalDate getValidUntil() {
+        return validUntil;
+    }
+
+    public AmlRecurringEscalationTier getEscalationTier() {
+        return escalationTier == null ? AmlRecurringEscalationTier.ROUTINE : AmlRecurringEscalationTier.valueOf(escalationTier);
+    }
+
+    public Integer getAlertsActioned() {
+        return alertsActioned;
+    }
+
+    /**
+     * Whether this review still holds the customer out of the review queue.
+     *
+     * <p>
+     * Two ways it stops standing. Its window runs out, or the customer's behaviour moves on far enough that the
+     * review no longer describes them - judged by how much the alert count has grown since, against the allowance for
+     * the tier it was taken at. A review with no window at all is a pre-existing one, and keeps the original rule of
+     * lapsing as soon as one more alert arrives.
+     */
+    public boolean stillStands(final int currentAlertCount) {
+        if (validUntil == null) {
+            return currentAlertCount <= alertCountAtReview;
+        }
+        if (LocalDate.now().isAfter(validUntil)) {
+            return false;
+        }
+        return currentAlertCount - alertCountAtReview < getEscalationTier().alertGrowthBeforeEarlyReturn();
+    }
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlStrCaseAlert.java

@@ -0,0 +1,83 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.time.LocalDateTime;
+
+/**
+ * One alert covered by an STR case.
+ *
+ * <p>
+ * A case escalated from a single transaction covers that one alert. A case raised off a customer's repeated behaviour
+ * covers all the alerts that make up the pattern - which is what an STR to FIU-IND actually describes, and what the
+ * Principal Officer has to be able to read in one place.
+ */
+@Entity
+@Table(name = "m_aml_str_case_alert")
+public class AmlStrCaseAlert {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne(optional = false)
+    @JoinColumn(name = "str_case_id", nullable = false)
+    private AmlStrCase strCase;
+
+    @ManyToOne(optional = false)
+    @JoinColumn(name = "alert_id", nullable = false)
+    private AmlAlert alert;
+
+    @Column(name = "added_on_utc", nullable = false)
+    private LocalDateTime addedOn;
+
+    protected AmlStrCaseAlert() {}
+
+    public static AmlStrCaseAlert link(final AmlStrCase strCase, final AmlAlert alert) {
+        final AmlStrCaseAlert link = new AmlStrCaseAlert();
+        link.strCase = strCase;
+        link.alert = alert;
+        link.addedOn = LocalDateTime.now();
+        return link;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public AmlStrCase getStrCase() {
+        return strCase;
+    }
+
+    public AmlAlert getAlert() {
+        return alert;
+    }
+
+    public LocalDateTime getAddedOn() {
+        return addedOn;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlStrCaseAlertRepository.java

@@ -0,0 +1,40 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.aml.domain;
+
+import java.util.List;
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AmlStrCaseAlertRepository extends JpaRepository<AmlStrCaseAlert, Long> {
+
+    /** The alerts one case covers, oldest first - the order the pattern happened in. */
+    List<AmlStrCaseAlert> findByStrCase_IdOrderByAlert_RaisedOnAsc(Long strCaseId);
+
+    /**
+     * The case already covering an alert, if any.
+     *
+     * <p>
+     * What stops a transaction reaching FIU-IND twice: an alert already inside a case is not attached to a second
+     * one, however it comes to be escalated again.
+     */
+    Optional<AmlStrCaseAlert> findByAlert_Id(Long alertId);
+
+    long countByStrCase_Id(Long strCaseId);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlStrCaseRepository.java

@@ -20,6 +20,7 @@ package org.apache.fineract.portfolio.aml.domain;
 
 import java.time.LocalDate;
 import java.util.List;
+import java.util.Optional;
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.query.Param;
@@ -28,6 +29,9 @@ public interface AmlStrCaseRepository extends JpaRepository<AmlStrCase, Long> {
 
     long countByClient_Id(Long clientId);
 
+    /** The case already open for a transaction, so escalating it again does not open a second one. */
+    Optional<AmlStrCase> findByAlertId(Long alertId);
+
     List<AmlStrCase> findByStatus(String status);
 
     @Query("SELECT c FROM AmlStrCase c WHERE c.status = 'CONCLUDED_SUSPICIOUS' AND c.concludedOn BETWEEN :from AND :to")

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlTransactionRule.java

@@ -84,6 +84,49 @@ public class AmlTransactionRule {
     @Column(name = "is_active", nullable = false)
     private boolean active;
 
+    /**
+     * CREDIT or DEBIT for a rule written about one direction only; null where either way qualifies.
+     * A rule named for withdrawals must not fire on a deposit.
+     */
+    @Column(name = "direction", length = 10)
+    private String direction;
+
+    /** True where only physical cash qualifies — a cash-reporting rule is not about transfers. */
+    @Column(name = "cash_only", nullable = false)
+    private boolean cashOnly;
+
+    /**
+     * How many transactions must make up the window before a pattern rule fires. Structuring is
+     * many small transactions; without this floor a single large one satisfies the window total and
+     * reads as a pattern it is not.
+     */
+    @Column(name = "min_transaction_count")
+    private Integer minTransactionCount;
+
+    /**
+     * Which customers a rule is about, where the rule is about the customer rather than the
+     * transaction: PEP, CHARITABLE_ORG, HIGH_RISK_BUSINESS, NEW_ACCOUNT. Null means the rule is
+     * about the transaction alone and so applies to everyone.
+     */
+    @Column(name = "subject_scope", length = 30)
+    private String subjectScope;
+
+    public String getSubjectScope() {
+        return subjectScope;
+    }
+
+    public String getDirection() {
+        return direction;
+    }
+
+    public boolean isCashOnly() {
+        return cashOnly;
+    }
+
+    public Integer getMinTransactionCount() {
+        return minTransactionCount;
+    }
+
     protected AmlTransactionRule() {}
 
     /**

fineract-core/src/main/java/org/apache/fineract/portfolio/aml/domain/AmlTransactionRuleRepository.java

@@ -18,6 +18,7 @@
  */
 package org.apache.fineract.portfolio.aml.domain;
 
+import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
 import org.springframework.data.jpa.repository.JpaRepository;
@@ -32,4 +33,10 @@ public interface AmlTransactionRuleRepository extends JpaRepository<AmlTransacti
      * by hand from the ledger.
      */
     Optional<AmlTransactionRule> findByRuleCode(String ruleCode);
+
+    /**
+     * Every rule named in the given codes, in one read. The alert screen resolves the rules each transaction matched
+     * into descriptions and severities; doing that a code at a time would be one query per rule per alert.
+     */
+    List<AmlTransactionRule> findByRuleCodeIn(Collection<String> ruleCodes);
 }

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientBehaviourWindow.java

@@ -0,0 +1,219 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+
+/**
+ * What one customer's money actually did over a period, and what that says about their rating.
+ *
+ * <p>
+ * A risk rating describes behaviour, and behaviour is a period rather than an event. Judging it from the alert feed
+ * meant a customer appeared the moment one transaction tripped a rule and was recommended for re-rating on that alone
+ * - a single shop purchase could argue for lowering a High rating, and a single large deposit for raising a Low one.
+ * Neither is a pattern.
+ *
+ * <p>
+ * One row is one window for one customer, computed nightly. Upgrades and downgrades read different windows, because
+ * the questions are not symmetric: a concern is about what the customer is doing now, and confidence needs a year of
+ * it. The suggestion is stored with the figures it was drawn from, so an officer reviewing it months later sees what
+ * the system was looking at rather than a conclusion with no working.
+ */
+@Entity
+@Table(name = "m_client_behaviour_window")
+public class ClientBehaviourWindow {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "client_id", nullable = false)
+    private Long clientId;
+
+    @Column(name = "window_from", nullable = false)
+    private LocalDate windowFrom;
+
+    @Column(name = "window_to", nullable = false)
+    private LocalDate windowTo;
+
+    @Column(name = "txn_count")
+    private Integer txnCount;
+
+    @Column(name = "distinct_months")
+    private Integer distinctMonths;
+
+    @Column(name = "credit_total", precision = 19, scale = 6)
+    private BigDecimal creditTotal;
+
+    @Column(name = "debit_total", precision = 19, scale = 6)
+    private BigDecimal debitTotal;
+
+    @Column(name = "largest_txn", precision = 19, scale = 6)
+    private BigDecimal largestTxn;
+
+    @Column(name = "cash_txn_count")
+    private Integer cashTxnCount;
+
+    @Column(name = "cash_total", precision = 19, scale = 6)
+    private BigDecimal cashTotal;
+
+    @Column(name = "large_txn_count")
+    private Integer largeTxnCount;
+
+    @Column(name = "declared_annual_income", precision = 19, scale = 6)
+    private BigDecimal declaredAnnualIncome;
+
+    @Column(name = "declared_annual_turnover", precision = 19, scale = 6)
+    private BigDecimal declaredAnnualTurnover;
+
+    @Column(name = "income_ratio", precision = 19, scale = 6)
+    private BigDecimal incomeRatio;
+
+    @Column(name = "alert_count")
+    private Integer alertCount;
+
+    @Column(name = "str_case_count")
+    private Integer strCaseCount;
+
+    @Column(name = "risk_category_at_review")
+    private Integer riskCategoryAtReview;
+
+    /** UP, DOWN or HOLD. */
+    @Column(name = "suggested_direction", length = 10)
+    private String suggestedDirection;
+
+    @Column(name = "suggested_category")
+    private Integer suggestedCategory;
+
+    @Column(name = "suggestion_reason", length = 500)
+    private String suggestionReason;
+
+    @Column(name = "computed_on")
+    private LocalDateTime computedOn;
+
+    protected ClientBehaviourWindow() {}
+
+    public static ClientBehaviourWindow of(final Long clientId, final LocalDate windowFrom, final LocalDate windowTo) {
+        final ClientBehaviourWindow window = new ClientBehaviourWindow();
+        window.clientId = clientId;
+        window.windowFrom = windowFrom;
+        window.windowTo = windowTo;
+        window.computedOn = LocalDateTime.now();
+        return window;
+    }
+
+    public void recordDistinctMonths(final Integer months) {
+        this.distinctMonths = months;
+    }
+
+    public Integer getDistinctMonths() {
+        return this.distinctMonths;
+    }
+
+    public void recordActivity(final Integer txnCount, final BigDecimal creditTotal, final BigDecimal debitTotal,
+            final BigDecimal largestTxn, final Integer cashTxnCount, final BigDecimal cashTotal, final Integer largeTxnCount) {
+        this.txnCount = txnCount;
+        this.creditTotal = creditTotal;
+        this.debitTotal = debitTotal;
+        this.largestTxn = largestTxn;
+        this.cashTxnCount = cashTxnCount;
+        this.cashTotal = cashTotal;
+        this.largeTxnCount = largeTxnCount;
+    }
+
+    public void recordMonitoring(final Integer alertCount, final Integer strCaseCount, final Integer riskCategoryAtReview) {
+        this.alertCount = alertCount;
+        this.strCaseCount = strCaseCount;
+        this.riskCategoryAtReview = riskCategoryAtReview;
+    }
+
+    /**
+     * Turnover measured against what the customer said to expect.
+     *
+     * <p>
+     * Null rather than zero when no income was declared: the ratio is unknown, not nil, and a rule that treats an
+     * unknown as a benign zero would clear every customer the bank never asked.
+     */
+    public void recordDeclared(final BigDecimal income, final BigDecimal turnover, final BigDecimal periodTurnover) {
+        this.declaredAnnualIncome = income;
+        this.declaredAnnualTurnover = turnover;
+        final BigDecimal basis = income != null && income.signum() > 0 ? income
+                : (turnover != null && turnover.signum() > 0 ? turnover : null);
+        this.incomeRatio = basis == null || periodTurnover == null ? null
+                : periodTurnover.divide(basis, 6, java.math.RoundingMode.HALF_UP);
+    }
+
+    public void recordSuggestion(final String direction, final Integer category, final String reason) {
+        this.suggestedDirection = direction;
+        this.suggestedCategory = category;
+        this.suggestionReason = reason == null || reason.length() <= 500 ? reason : reason.substring(0, 500);
+    }
+
+    public Long getClientId() {
+        return this.clientId;
+    }
+
+    public LocalDate getWindowFrom() {
+        return this.windowFrom;
+    }
+
+    public LocalDate getWindowTo() {
+        return this.windowTo;
+    }
+
+    public Integer getTxnCount() {
+        return this.txnCount;
+    }
+
+    public BigDecimal getCashTotal() {
+        return this.cashTotal;
+    }
+
+    public Integer getLargeTxnCount() {
+        return this.largeTxnCount;
+    }
+
+    public Integer getAlertCount() {
+        return this.alertCount;
+    }
+
+    public Integer getStrCaseCount() {
+        return this.strCaseCount;
+    }
+
+    public Integer getRiskCategoryAtReview() {
+        return this.riskCategoryAtReview;
+    }
+
+    public String getSuggestedDirection() {
+        return this.suggestedDirection;
+    }
+
+    public Integer getSuggestedCategory() {
+        return this.suggestedCategory;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientBehaviourWindowRepository.java

@@ -0,0 +1,43 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import java.time.LocalDate;
+import java.util.List;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+public interface ClientBehaviourWindowRepository extends JpaRepository<ClientBehaviourWindow, Long> {
+
+    List<ClientBehaviourWindow> findByClientId(Long clientId);
+
+    /**
+     * Clears the windows computed for a given day before the job writes that day's.
+     *
+     * <p>
+     * The job is a recomputation, not an append. Re-running it - after a failure, or twice in a night - must leave one
+     * set of windows rather than a customer appearing several times on the review screen with slightly different
+     * figures.
+     */
+    @Modifying
+    @Query("DELETE FROM ClientBehaviourWindow w WHERE w.windowTo = :windowTo")
+    void deleteByWindowTo(@Param("windowTo") LocalDate windowTo);
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientKyc.java

@@ -291,6 +291,31 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     @Column(name = "form15_fy", length = 10)
     private String form15Fy;
 
+    // ── Risk profile ─────────────────────────────────────────────────────────
+    /**
+     * Customer facts the risk re-rating policy tests against, as against anything the customer transacted.
+     *
+     * <p>
+     * A politically exposed person is not downgraded because their activity looks ordinary — that is precisely the
+     * risk — and the same holds for a sanctions or adverse-media match. False means "not recorded as such", which is
+     * the correct reading for a book where nobody was ever asked; it is not an assertion that the customer is clean.
+     */
+    @Column(name = "is_pep", nullable = false)
+    private boolean isPep;
+
+    @Column(name = "sanctions_match", nullable = false)
+    private boolean sanctionsMatch;
+
+    @Column(name = "adverse_media_match", nullable = false)
+    private boolean adverseMediaMatch;
+
+    /** What the customer told the bank to expect, which their actual turnover is measured against. */
+    @Column(name = "declared_annual_income", precision = 19, scale = 6)
+    private BigDecimal declaredAnnualIncome;
+
+    @Column(name = "declared_annual_turnover", precision = 19, scale = 6)
+    private BigDecimal declaredAnnualTurnover;
+
     // ── CKYCRR ───────────────────────────────────────────────────────────────
     /** Central KYC Records Registry number issued by CERSAI */
     @Column(name = "ckyc_number", length = 14)
@@ -355,7 +380,7 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         this.dinVerified = false;
         this.isException = false;
         this.exceptionResolved = false;
-        this.initiatedOn = DateUtils.getLocalDateOfTenant();
+        this.initiatedOn = DateUtils.getBusinessLocalDate();
     }
 
     public static ClientKyc initiateKyc(final Client client, final JsonCommand command) {
@@ -527,6 +552,19 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
                 v -> this.aadhaarReceiptRemarks = v);
         updateDateField(command, "aadhaarReceiptTakenOn", this.aadhaarReceiptTakenOn, actualChanges,
                 v -> this.aadhaarReceiptTakenOn = v);
+        // Risk profile. These are determinations about the customer rather than about a transaction, and the
+        // re-rating policy reads them directly: a PEP or a sanctions match holds a rating at High however ordinary the
+        // period's activity looks.
+        updateBooleanField(command, "isPep", this.isPep, actualChanges, v -> this.isPep = v != null ? v : false);
+        updateBooleanField(command, "sanctionsMatch", this.sanctionsMatch, actualChanges,
+                v -> this.sanctionsMatch = v != null ? v : false);
+        updateBooleanField(command, "adverseMediaMatch", this.adverseMediaMatch, actualChanges,
+                v -> this.adverseMediaMatch = v != null ? v : false);
+        updateBigDecimalField(command, "declaredAnnualIncome", this.declaredAnnualIncome, actualChanges,
+                v -> this.declaredAnnualIncome = v);
+        updateBigDecimalField(command, "declaredAnnualTurnover", this.declaredAnnualTurnover, actualChanges,
+                v -> this.declaredAnnualTurnover = v);
+
         updateStringField(command, "enterprisePan", this.enterprisePan, actualChanges, v -> this.enterprisePan = v);
         updateStringField(command, "cinNumber", this.cinNumber, actualChanges, v -> this.cinNumber = v);
         updateStringField(command, "dinNumber", this.dinNumber, actualChanges, v -> this.dinNumber = v);
@@ -562,10 +600,21 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
                 v -> this.form15Applicable = v);
         updateStringField(command, "form15Type", this.form15Type, actualChanges, v -> this.form15Type = v);
         updateStringField(command, "form15FY", this.form15Fy, actualChanges, v -> this.form15Fy = v);
-        updateBooleanField(command, "isException", this.isException, actualChanges, v -> this.isException = v != null ? v : false);
-        updateStringField(command, "exceptionReason", this.exceptionReason, actualChanges, v -> this.exceptionReason = v);
-        updateBooleanField(command, "exceptionResolved", this.exceptionResolved, actualChanges, v -> this.exceptionResolved = v != null ? v : false);
-        updateDateField(command, "exceptionResolvedOn", this.exceptionResolvedOn, actualChanges, v -> this.exceptionResolvedOn = v);
+        // The four exception columns are derived from whether the identity checks have passed, not
+        // data an officer types, so they are updated without recording an overwrite. A verified
+        // record demands remarks for any field it already held (see
+        // getFieldsOverwrittenByLastUpdate), and is_exception is never null once written — so
+        // counting these would make closing a settled exception impossible without a justification
+        // for something nobody chose. That is what left clients verified on the KYC tab while the
+        // exceptions register still listed them as Pending.
+        updateDerivedBooleanField(command, "isException", this.isException, actualChanges,
+                v -> this.isException = v != null ? v : false);
+        updateDerivedStringField(command, "exceptionReason", this.exceptionReason, actualChanges,
+                v -> this.exceptionReason = v);
+        updateDerivedBooleanField(command, "exceptionResolved", this.exceptionResolved, actualChanges,
+                v -> this.exceptionResolved = v != null ? v : false);
+        updateDerivedDateField(command, "exceptionResolvedOn", this.exceptionResolvedOn, actualChanges,
+                v -> this.exceptionResolvedOn = v);
         updateBooleanField(command, "panVerified", this.panVerified, actualChanges, v -> this.panVerified = v != null ? v : false);
         updateBooleanField(command, "aadhaarVerified", this.aadhaarVerified, actualChanges, v -> this.aadhaarVerified = v != null ? v : false);
         updateBooleanField(command, "gstinVerified", this.gstinVerified, actualChanges, v -> this.gstinVerified = v != null ? v : false);
@@ -620,6 +669,44 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
      * populated is the record being completed rather than altered, so it is deliberately not
      * recorded — see {@link #getFieldsOverwrittenByLastUpdate()}.
      */
+    /*
+     * Derived-field variants of the update helpers above.
+     *
+     * Identical, minus the recordOverwrite call: these columns are computed from whether the
+     * identity checks have passed rather than entered by an officer, so replacing one is not the
+     * kind of change a verified record demands a justification for. They still report into
+     * `changes`, so the update is persisted and audited like any other.
+     */
+
+    private void updateDerivedBooleanField(final JsonCommand command, final String param, final Boolean current,
+            final Map<String, Object> changes, final java.util.function.Consumer<Boolean> setter) {
+        if (command.parameterExists(param)) {
+            final Boolean newValue = command.booleanObjectValueOfParameterNamed(param);
+            if ((newValue == null && current != null) || (newValue != null && !newValue.equals(current))) {
+                changes.put(param, newValue);
+                setter.accept(newValue);
+            }
+        }
+    }
+
+    private void updateDerivedStringField(final JsonCommand command, final String param, final String current,
+            final Map<String, Object> changes, final java.util.function.Consumer<String> setter) {
+        if (command.isChangeInStringParameterNamed(param, current)) {
+            final String newValue = command.stringValueOfParameterNamed(param);
+            changes.put(param, newValue);
+            setter.accept(StringUtils.defaultIfEmpty(newValue, null));
+        }
+    }
+
+    private void updateDerivedDateField(final JsonCommand command, final String param, final LocalDate current,
+            final Map<String, Object> changes, final java.util.function.Consumer<LocalDate> setter) {
+        if (command.isChangeInLocalDateParameterNamed(param, current)) {
+            final LocalDate newValue = command.localDateValueOfParameterNamed(param);
+            changes.put(param, newValue);
+            setter.accept(newValue);
+        }
+    }
+
     private void recordOverwrite(final String param, final Object currentValue) {
         final boolean wasPopulated = currentValue instanceof String text
                 ? StringUtils.isNotBlank(text)
@@ -670,13 +757,13 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
     public void markCkycUploaded(final String ckycNumber, final String batchId) {
         this.ckycNumber = StringUtils.defaultIfEmpty(ckycNumber, null);
         this.ckycBatchId = StringUtils.defaultIfEmpty(batchId, null);
-        this.ckycUploadedOn = DateUtils.getLocalDateOfTenant();
+        this.ckycUploadedOn = DateUtils.getBusinessLocalDate();
     }
 
     /** Called after successful 3rd-party verification of all required documents. */
     public void markVerified(final String ckycNumber) {
         this.kycStatus = ClientKycStatus.VERIFIED.getValue();
-        this.verifiedOn = DateUtils.getLocalDateOfTenant();
+        this.verifiedOn = DateUtils.getBusinessLocalDate();
         this.ckycNumber = StringUtils.defaultIfEmpty(ckycNumber, null);
 
         final KycRiskCategory risk = KycRiskCategory.fromInt(this.riskCategory);
@@ -709,21 +796,21 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
             return this.expiryDate;
         }
 
-        this.expiryDate = DateUtils.getLocalDateOfTenant().plusYears(risk.getReKycYears());
+        this.expiryDate = DateUtils.getBusinessLocalDate().plusYears(risk.getReKycYears());
         return this.expiryDate;
     }
 
     /** Called when verification fails. */
     public void markRejected(final String remarks) {
         this.kycStatus = ClientKycStatus.REJECTED.getValue();
-        this.rejectedOn = DateUtils.getLocalDateOfTenant();
+        this.rejectedOn = DateUtils.getBusinessLocalDate();
         this.remarks = StringUtils.defaultIfEmpty(remarks, this.remarks);
     }
 
     public void markPanVerified(final String fullName, final String firstName, final String lastName,
             final String aadhaarSeedingStatus, final String category, final String status) {
         this.panVerified = true;
-        this.panVerifiedOn = DateUtils.getLocalDateOfTenant();
+        this.panVerifiedOn = DateUtils.getBusinessLocalDate();
         this.panFullName = StringUtils.defaultIfEmpty(fullName, null);
         this.panFirstName = StringUtils.defaultIfEmpty(firstName, null);
         this.panLastName = StringUtils.defaultIfEmpty(lastName, null);
@@ -749,28 +836,28 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
 
     public void markAadhaarVerified() {
         this.aadhaarVerified = true;
-        this.aadhaarVerifiedOn = DateUtils.getLocalDateOfTenant();
+        this.aadhaarVerifiedOn = DateUtils.getBusinessLocalDate();
     }
 
     public void markGstinVerified() {
         this.gstinVerified = true;
-        this.gstinVerifiedOn = DateUtils.getLocalDateOfTenant();
+        this.gstinVerifiedOn = DateUtils.getBusinessLocalDate();
     }
 
     public void markCinVerified() {
         this.cinVerified = true;
-        this.cinVerifiedOn = DateUtils.getLocalDateOfTenant();
+        this.cinVerifiedOn = DateUtils.getBusinessLocalDate();
     }
 
     public void markDinVerified() {
         this.dinVerified = true;
-        this.dinVerifiedOn = DateUtils.getLocalDateOfTenant();
+        this.dinVerifiedOn = DateUtils.getBusinessLocalDate();
     }
 
     public void markDinVerified(final String dinNumber, final String mcaResponseJson) {
         this.dinNumber = dinNumber;
         this.dinVerified = true;
-        this.dinVerifiedOn = DateUtils.getLocalDateOfTenant();
+        this.dinVerifiedOn = DateUtils.getBusinessLocalDate();
         this.isDirector = true;
         this.dinMcaResponse = mcaResponseJson;
     }
@@ -791,7 +878,17 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         } else if (type != null && type.isNonIndividual()) {
             allDone = this.panVerified && this.gstinVerified;
         }
-        if (allDone && !getKycStatus().isVerified()) {
+        // Re-stamped even when the record already reads VERIFIED, because that is exactly what a
+        // periodic re-KYC is: an already-verified customer verified afresh.
+        //
+        // Skipping it there left verifiedOn — and with it the expiry date, and the dormancy clock
+        // that now measures from it — frozen at the original onboarding. An officer who re-verified
+        // both PAN and Aadhaar at the counter saw both rows stamped with today's date and the
+        // account still sitting on the inactive report, with nothing to say what was missing.
+        //
+        // Guarded on the verifications rather than the status, so this only fires when the checks
+        // that constitute a verification have actually been done again.
+        if (allDone) {
             markVerified(this.ckycNumber);
         }
         return allDone;
@@ -839,6 +936,26 @@ public class ClientKyc extends AbstractAuditableWithUTCDateTimeCustom<Long> {
         recalculateExpiryForRiskCategory();
     }
 
+    public boolean isPep() {
+        return this.isPep;
+    }
+
+    public boolean isSanctionsMatch() {
+        return this.sanctionsMatch;
+    }
+
+    public boolean isAdverseMediaMatch() {
+        return this.adverseMediaMatch;
+    }
+
+    public BigDecimal getDeclaredAnnualIncome() {
+        return this.declaredAnnualIncome;
+    }
+
+    public BigDecimal getDeclaredAnnualTurnover() {
+        return this.declaredAnnualTurnover;
+    }
+
     public String getPanNumber() {
         return panNumber;
     }

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/ClientRiskRule.java

@@ -93,6 +93,26 @@ public class ClientRiskRule {
     @Column(name = "order_position", nullable = false)
     private Integer orderPosition;
 
+    /**
+     * Which of the two rule families this row belongs to - {@link #KIND_KYC} or {@link #KIND_AML}.
+     *
+     * This table carries both, and they are not interchangeable. A KYC rule is profile-driven: it
+     * reads occupation / income / turnover to categorise a customer at onboarding (RBI Master
+     * Direction on KYC, Section 12). An AML rule is behaviour-driven: it describes a transaction
+     * pattern and may only fire against posted transactions, surfacing in {@code m_aml_alert}
+     * (Section 13).
+     *
+     * The distinction used to be inferred from "has no criteria set", which migration 0448 erased
+     * by writing 0.0 over the NULLs - after which transaction-monitoring rules began matching
+     * ordinary customers at onboarding and pre-flagging them for AML. Recording the kind means a
+     * rule states what it is; nothing has to guess from the shape of its other columns.
+     */
+    @Column(name = "rule_kind", length = 10)
+    private String ruleKind;
+
+    public static final String KIND_KYC = "KYC";
+    public static final String KIND_AML = "AML";
+
     protected ClientRiskRule() {}
 
     /**
@@ -104,8 +124,9 @@ public class ClientRiskRule {
             final BigDecimal maxMonthlyIncome, final BigDecimal minAnnualIncome, final BigDecimal maxAnnualIncome,
             final BigDecimal minAnnualTurnover, final BigDecimal maxAnnualTurnover, final String amlCheckStatus,
             final String bannedEntityMatch, final String willfulDefaulter, final String ecgcSalFlag,
-            final String dormantFlag) {
+            final String dormantFlag, final String ruleKind) {
         final ClientRiskRule rule = new ClientRiskRule();
+        rule.ruleKind = ruleKind;
         rule.ruleName = ruleName;
         rule.reason = reason;
         rule.riskCategory = riskCategory;
@@ -137,6 +158,19 @@ public class ClientRiskRule {
         return id;
     }
 
+    public String getRuleKind() {
+        return ruleKind;
+    }
+
+    /**
+     * True when this rule may take part in onboarding risk categorisation. Rows predating the
+     * rule_kind column are treated as KYC, matching how they behaved before AML rules were seeded
+     * into the same table.
+     */
+    public boolean isKycRule() {
+        return !KIND_AML.equalsIgnoreCase(this.ruleKind);
+    }
+
     public String getRuleName() {
         return ruleName;
     }

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/RiskPolicyParameter.java

@@ -0,0 +1,74 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+/**
+ * One number the risk re-rating policy is made of - a window length, a minimum transaction count, a cash threshold.
+ *
+ * <p>
+ * Held as data because these are the bank's risk appetite rather than engineering constants. How long a customer must
+ * behave before a High rating comes down is a compliance judgement, and a co-operative bank whose members transact
+ * three times a month needs different figures from one lending to traders.
+ */
+@Entity
+@Table(name = "m_risk_policy_parameter")
+public class RiskPolicyParameter {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "parameter_key", nullable = false, length = 80)
+    private String parameterKey;
+
+    @Column(name = "parameter_value", nullable = false, precision = 19, scale = 2)
+    private BigDecimal parameterValue;
+
+    @Column(name = "description", length = 500)
+    private String description;
+
+    @Column(name = "last_modified_by")
+    private Long lastModifiedBy;
+
+    @Column(name = "last_modified_on")
+    private LocalDateTime lastModifiedOn;
+
+    protected RiskPolicyParameter() {}
+
+    public String getParameterKey() {
+        return this.parameterKey;
+    }
+
+    public BigDecimal getParameterValue() {
+        return this.parameterValue;
+    }
+
+    public String getDescription() {
+        return this.description;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/client/domain/RiskPolicyParameterRepository.java

@@ -0,0 +1,23 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.client.domain;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface RiskPolicyParameterRepository extends JpaRepository<RiskPolicyParameter, Long> {}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/accounttype/data/DdsAccountTypeData.java

@@ -0,0 +1,61 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.accounttype.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import lombok.Builder;
+import lombok.Getter;
+
+/**
+ * Immutable data object representing a DDS Account Type (the legacy Account Type Creation record).
+ */
+@Getter
+@Builder(toBuilder = true)
+public final class DdsAccountTypeData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final String accountTypeGroup;
+    private final String accountTypeCode;
+    private final String accountTypeDescription;
+    private final Boolean autoInterestPost;
+    private final String autoInterestPostWhen;
+    private final Integer autoInterestPostDay;
+    /** Whether an account on this scheme closes itself on its maturity date. */
+    private final Boolean maturityAutoClose;
+    /**
+     * What this scheme charges for closing an account before its term is up: how long it may not be
+     * closed at all, what comes off the customer's rate if they bear the cost, and what comes off the
+     * agent's commission either way. Read at the moment of closure, so a change on the scheme takes
+     * effect on accounts already open.
+     */
+    private final Integer prematureLockinMonths;
+    private final BigDecimal prematureInterestReduction;
+    private final BigDecimal prematureAgentCommissionPenalty;
+    /** The scheme's annual interest rate, which an account opened on it takes. */
+    private final BigDecimal interestRate;
+    private final Boolean active;
+    private final LocalDateTime createdDate;
+    private final LocalDateTime lastModifiedDate;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/accounttype/domain/DdsAccountType.java

@@ -0,0 +1,267 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.accounttype.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+import java.math.BigDecimal;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+
+/**
+ * A DDS scheme variant, as registered on the legacy "Account Type Creation" screen: a group (e.g.
+ * "DDS"), a short code (e.g. "DS"), a description (e.g. "DAILY DEPOSIT"), and whether interest is
+ * posted automatically and how often.
+ *
+ * This is master/reference data, not a deposit product - a Party picks one of these by code in its
+ * "Sub Type" field. Nothing here drives interest calculation: the DDS batch job accrues interest
+ * straight off each Party's own rate and balance.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_account_type", uniqueConstraints = {
+        @UniqueConstraint(columnNames = { "account_type_code" }, name = "uq_dds_account_type_code") })
+public class DdsAccountType extends AbstractAuditableCustom {
+
+    @Column(name = "account_type_group", length = 60, nullable = false)
+    private String accountTypeGroup;
+
+    @Column(name = "account_type_code", length = 20, nullable = false)
+    private String accountTypeCode;
+
+    @Column(name = "account_type_description", length = 200, nullable = false)
+    private String accountTypeDescription;
+
+    @Column(name = "auto_interest_post", nullable = false)
+    private boolean autoInterestPost;
+
+    @Column(name = "auto_interest_post_when", length = 20)
+    private String autoInterestPostWhen;
+
+    /** Day of the month interest posts on. Only meaningful when {@code autoInterestPost} is set. */
+    @Column(name = "auto_interest_post_day")
+    private Integer autoInterestPostDay;
+
+    /**
+     * Whether an account on this scheme closes itself the day it matures, instead of waiting for a
+     * clerk to pay it out by hand.
+     *
+     * Kept on the scheme rather than switched on bank-wide, for the same reason interest posting is:
+     * a bank runs several schemes at once and will not want them all behaving the same way. It says
+     * only whether the closing should happen, never when - the batch run decides that, exactly as it
+     * does for {@code autoInterestPost}.
+     *
+     * A scheme with this set still only closes an account that has somewhere for the money to go. If
+     * the account names no savings account to be paid into, nothing happens automatically and the
+     * clerk pays it out as before: money is never sent somewhere nobody chose.
+     */
+    @Column(name = "maturity_auto_close", nullable = false)
+    private boolean maturityAutoClose;
+
+    /**
+     * How long an account on this scheme must run before it may be closed early at all. Below this
+     * the request is refused outright rather than charged for.
+     *
+     * Per-scheme rather than one bank-wide figure: a lock-in longer than the scheme's own term would
+     * make early closure unreachable, so a two-month scheme and a five-year one cannot share one.
+     */
+    @Column(name = "premature_lockin_months", nullable = false)
+    private Integer prematureLockinMonths;
+
+    /**
+     * Percentage points off the customer's interest rate when the customer bears the cost of closing
+     * early - a 2% scheme pays 1% over the whole period, not only the part left to run.
+     */
+    @Column(name = "premature_interest_reduction", scale = 6, precision = 19, nullable = false)
+    private BigDecimal prematureInterestReduction;
+
+    /**
+     * Percentage off the collecting agent's commission on an early closure, applied whichever way the
+     * shortfall is met - an account closed early is a round the agent did not keep going.
+     */
+    @Column(name = "premature_agent_commission_penalty", scale = 6, precision = 19, nullable = false)
+    private BigDecimal prematureAgentCommissionPenalty;
+
+    /**
+     * The scheme's annual interest rate. Mandatory: an account opened on the scheme takes this rate,
+     * rather than one typed at the counter for each customer.
+     */
+    @Column(name = "interest_rate", scale = 6, precision = 19, nullable = false)
+    private BigDecimal interestRate;
+
+    /**
+     * An account type is retired by deactivating it, never by deleting: Parties are opened against
+     * it, so removing the row would orphan every account already using it. Inactive types stay out
+     * of the pick lists for new accounts but leave existing accounts untouched.
+     */
+    @Column(name = "is_active", nullable = false)
+    private boolean active;
+
+    protected DdsAccountType() {
+        //
+    }
+
+    private DdsAccountType(final JsonCommand command) {
+        this.accountTypeGroup = command.stringValueOfParameterNamed("accountTypeGroup");
+        this.accountTypeCode = normaliseCode(command.stringValueOfParameterNamed("accountTypeCode"));
+        this.accountTypeDescription = command.stringValueOfParameterNamed("accountTypeDescription");
+        this.autoInterestPost = command.booleanPrimitiveValueOfParameterNamed("autoInterestPost");
+        this.autoInterestPostWhen = StringUtils
+                .defaultIfEmpty(command.stringValueOfParameterNamedAllowingNull("autoInterestPostWhen"), null);
+        this.autoInterestPostDay = this.autoInterestPost
+                ? command.integerValueOfParameterNamedDefaultToNullIfZero("autoInterestPostDay")
+                : null;
+        this.maturityAutoClose = command.booleanPrimitiveValueOfParameterNamed("maturityAutoClose");
+        this.prematureLockinMonths = valueOr(command, "prematureLockinMonths", DEFAULT_LOCKIN_MONTHS);
+        this.prematureInterestReduction = valueOr(command, "prematureInterestReduction", DEFAULT_INTEREST_REDUCTION);
+        this.prematureAgentCommissionPenalty = valueOr(command, "prematureAgentCommissionPenalty", DEFAULT_AGENT_PENALTY);
+        this.interestRate = command.bigDecimalValueOfParameterNamed("interestRate");
+        // A newly created account type is available for use straight away.
+        this.active = !command.parameterExists("active") || command.booleanPrimitiveValueOfParameterNamed("active");
+    }
+
+    /**
+     * The bank's stated terms, used when a scheme is created without saying otherwise. They are
+     * defaults rather than fixed rules - the screen offers them and the bank changes them per scheme.
+     */
+    private static final int DEFAULT_LOCKIN_MONTHS = 12;
+    private static final BigDecimal DEFAULT_INTEREST_REDUCTION = BigDecimal.ONE;
+    private static final BigDecimal DEFAULT_AGENT_PENALTY = BigDecimal.ONE;
+
+    private static Integer valueOr(final JsonCommand command, final String parameter, final int fallback) {
+        final Integer supplied = command.parameterExists(parameter)
+                ? command.integerValueOfParameterNamedDefaultToNullIfZero(parameter)
+                : null;
+        return supplied == null ? fallback : supplied;
+    }
+
+    private static BigDecimal valueOr(final JsonCommand command, final String parameter, final BigDecimal fallback) {
+        // Deliberately not "default to null if zero": zero is a real answer here - a scheme that
+        // charges the customer nothing for closing early - and must not be read as "unset".
+        final BigDecimal supplied = command.parameterExists(parameter)
+                ? command.bigDecimalValueOfParameterNamed(parameter)
+                : null;
+        return supplied == null ? fallback : supplied;
+    }
+
+    /**
+     * Codes are the account type's identity and are matched against elsewhere, so "ds" and "DS" must
+     * not become two different types - they are stored upper-cased and trimmed.
+     */
+    private static String normaliseCode(final String code) {
+        return code == null ? null : code.trim().toUpperCase();
+    }
+
+    public static DdsAccountType fromJson(final JsonCommand command) {
+        return new DdsAccountType(command);
+    }
+
+    public Map<String, Object> update(final JsonCommand command) {
+
+        final Map<String, Object> actualChanges = new LinkedHashMap<>(6);
+
+        if (command.isChangeInStringParameterNamed("accountTypeGroup", this.accountTypeGroup)) {
+            final String newValue = command.stringValueOfParameterNamed("accountTypeGroup");
+            actualChanges.put("accountTypeGroup", newValue);
+            this.accountTypeGroup = newValue;
+        }
+
+        final String incomingCode = normaliseCode(command.stringValueOfParameterNamedAllowingNull("accountTypeCode"));
+        if (incomingCode != null && !incomingCode.equals(this.accountTypeCode)) {
+            actualChanges.put("accountTypeCode", incomingCode);
+            this.accountTypeCode = incomingCode;
+        }
+
+        if (command.isChangeInStringParameterNamed("accountTypeDescription", this.accountTypeDescription)) {
+            final String newValue = command.stringValueOfParameterNamed("accountTypeDescription");
+            actualChanges.put("accountTypeDescription", newValue);
+            this.accountTypeDescription = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("autoInterestPost", this.autoInterestPost)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("autoInterestPost");
+            actualChanges.put("autoInterestPost", newValue);
+            this.autoInterestPost = newValue;
+        }
+
+        if (command.isChangeInStringParameterNamed("autoInterestPostWhen", this.autoInterestPostWhen)) {
+            final String newValue = command.stringValueOfParameterNamed("autoInterestPostWhen");
+            actualChanges.put("autoInterestPostWhen", newValue);
+            this.autoInterestPostWhen = StringUtils.defaultIfEmpty(newValue, null);
+        }
+
+        if (command.isChangeInIntegerParameterNamed("autoInterestPostDay", this.autoInterestPostDay)) {
+            final Integer newValue = command.integerValueOfParameterNamedDefaultToNullIfZero("autoInterestPostDay");
+            actualChanges.put("autoInterestPostDay", newValue);
+            this.autoInterestPostDay = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("maturityAutoClose", this.maturityAutoClose)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("maturityAutoClose");
+            actualChanges.put("maturityAutoClose", newValue);
+            this.maturityAutoClose = newValue;
+        }
+
+        // A posting day only means anything while auto-posting is on.
+        if (!this.autoInterestPost) {
+            this.autoInterestPostDay = null;
+        }
+
+        if (command.isChangeInIntegerParameterNamed("prematureLockinMonths", this.prematureLockinMonths)) {
+            final Integer newValue = command.integerValueOfParameterNamedDefaultToNullIfZero("prematureLockinMonths");
+            actualChanges.put("prematureLockinMonths", newValue);
+            // Zero lock-in is meaningful - it lets an account be closed early from day one - but the
+            // column cannot hold null, so it is kept as zero rather than reset to the default.
+            this.prematureLockinMonths = newValue == null ? 0 : newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("prematureInterestReduction", this.prematureInterestReduction)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("prematureInterestReduction");
+            actualChanges.put("prematureInterestReduction", newValue);
+            this.prematureInterestReduction = newValue == null ? BigDecimal.ZERO : newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("prematureAgentCommissionPenalty", this.prematureAgentCommissionPenalty)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("prematureAgentCommissionPenalty");
+            actualChanges.put("prematureAgentCommissionPenalty", newValue);
+            this.prematureAgentCommissionPenalty = newValue == null ? BigDecimal.ZERO : newValue;
+        }
+
+        // The scheme's rate - every open account on it follows it (see the account type service).
+        if (command.parameterExists("interestRate") && command.isChangeInBigDecimalParameterNamed("interestRate", this.interestRate)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("interestRate");
+            actualChanges.put("interestRate", newValue);
+            this.interestRate = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("active", this.active)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("active");
+            actualChanges.put("active", newValue);
+            this.active = newValue;
+        }
+
+        return actualChanges;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/accounttype/exception/DdsAccountTypeNotFoundException.java

@@ -0,0 +1,36 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.accounttype.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+import org.springframework.dao.EmptyResultDataAccessException;
+
+/**
+ * A {@link RuntimeException} thrown when a DDS account type resource is not found.
+ */
+public class DdsAccountTypeNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public DdsAccountTypeNotFoundException(final Long id) {
+        super("error.msg.dds.account.type.id.invalid", "DDS account type with identifier " + id + " does not exist", id);
+    }
+
+    public DdsAccountTypeNotFoundException(final Long id, final EmptyResultDataAccessException e) {
+        super("error.msg.dds.account.type.id.invalid", "DDS account type with identifier " + id + " does not exist", id, e);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/data/BatchRunData.java

@@ -0,0 +1,58 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.Collection;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder(toBuilder = true)
+public final class BatchRunData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final String jobType;
+    private final String branchScope;
+
+    /** Which DDS scheme the run covered, or null for every scheme. Set by the automatic posting job. */
+    private final String subType;
+
+    private final LocalDate jobDate;
+    private final Long agentFrom;
+    private final Long agentTo;
+    private final Long partyFrom;
+    private final Long partyTo;
+    private final String status;
+    private final Integer totalRows;
+    /** How many rows a crediting run has applied. Equal to totalRows once it has finished. */
+    private final Integer rowsPosted;
+    /** Why a run stopped, when it did - a crediting run happens in the background and has no other voice. */
+    private final String failureReason;
+    private final BigDecimal totalAmount;
+    private final LocalDate generatedOnDate;
+    private final LocalDate postedOnDate;
+    private final Collection<BatchRunRowData> rows;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/data/BatchRunRowData.java

@@ -0,0 +1,57 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+public final class BatchRunRowData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long partyId;
+    private final String partyCode;
+    private final String partyName;
+    private final Long agentId;
+    private final String agentCode;
+    private final String agentName;
+
+    /** What the row applies: interest, or commission net of every deduction. */
+    private final BigDecimal amount;
+
+    /**
+     * How that amount was arrived at. Null on rows where it does not apply - a posting row moves a
+     * figure an earlier calculation run worked out, so the rate and base belong to that run.
+     */
+    private final BigDecimal baseAmount;
+    private final BigDecimal ratePercent;
+    private final BigDecimal grossAmount;
+    private final BigDecimal tdsAmount;
+    private final BigDecimal deductionAmount;
+    private final LocalDate fromDate;
+    private final LocalDate toDate;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/domain/BatchRun.java

@@ -0,0 +1,180 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.domain;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.List;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+
+/**
+ * One Calculate-then-Post batch run - the deliberate two-step control from the legacy Interest Part
+ * menu (Interest Calculation -> Interest Posting, OD Interest Calculation -> OD Interest Posting,
+ * Commission Calculation -> Commission Posting): a run is generated (rows computed and saved as a
+ * preview, nothing else changes), then posted (a separate, explicit step that applies exactly the
+ * rows that were previewed - never a fresh recalculation, so what gets applied is always what was
+ * seen).
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_batch_run")
+public class BatchRun extends AbstractAuditableCustom {
+
+    @Column(name = "job_type", length = 40, nullable = false)
+    private String jobType;
+
+    @Column(name = "branch_scope", length = 20, nullable = false)
+    private String branchScope;
+
+    /**
+     * Which DDS scheme this run covered, or null for every scheme.
+     *
+     * A posting day belongs to an account type rather than to the bank, so a run started by the
+     * scheduled job covers one scheme at a time - otherwise the scheme due on the 15th would drag the
+     * month-end scheme's accounts along with it. A run started by hand from the screen leaves this
+     * null and covers everything, as it always did.
+     */
+    @Column(name = "sub_type", length = 60)
+    private String subType;
+
+    @Column(name = "job_date", nullable = false)
+    private LocalDate jobDate;
+
+    @Column(name = "agent_from", nullable = false)
+    private Long agentFrom;
+
+    @Column(name = "agent_to", nullable = false)
+    private Long agentTo;
+
+    @Column(name = "party_from")
+    private Long partyFrom;
+
+    @Column(name = "party_to")
+    private Long partyTo;
+
+    @Column(name = "status", length = 20, nullable = false)
+    private String status;
+
+    @Column(name = "total_rows", nullable = false)
+    private Integer totalRows;
+
+    /** How many of those rows have been credited so far - what a screen reads to show progress. */
+    @Column(name = "rows_posted", nullable = false)
+    private Integer rowsPosted = 0;
+
+    /** Why a run stopped, when it did. A background run has nowhere else to say so. */
+    @Column(name = "failure_reason", length = 500)
+    private String failureReason;
+
+    @Column(name = "total_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal totalAmount;
+
+    @Column(name = "generated_on_date", nullable = false)
+    private LocalDate generatedOnDate;
+
+    @Column(name = "posted_on_date")
+    private LocalDate postedOnDate;
+
+    @OneToMany(mappedBy = "batchRun", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+    @OrderBy("id")
+    private List<BatchRunRow> rows = new ArrayList<>();
+
+    protected BatchRun() {
+        //
+    }
+
+    public BatchRun(final String jobType, final String branchScope, final LocalDate jobDate, final Long agentFrom,
+            final Long agentTo, final Long partyFrom, final Long partyTo, final LocalDate generatedOnDate) {
+        this(jobType, branchScope, jobDate, agentFrom, agentTo, partyFrom, partyTo, generatedOnDate, null);
+    }
+
+    public BatchRun(final String jobType, final String branchScope, final LocalDate jobDate, final Long agentFrom,
+            final Long agentTo, final Long partyFrom, final Long partyTo, final LocalDate generatedOnDate, final String subType) {
+        this.jobType = jobType;
+        this.branchScope = branchScope;
+        this.subType = subType;
+        this.jobDate = jobDate;
+        this.agentFrom = agentFrom;
+        this.agentTo = agentTo;
+        this.partyFrom = partyFrom;
+        this.partyTo = partyTo;
+        this.status = "CALCULATED";
+        this.totalRows = 0;
+        this.totalAmount = BigDecimal.ZERO;
+        this.generatedOnDate = generatedOnDate;
+    }
+
+    public void addRow(final BatchRunRow row) {
+        row.setBatchRun(this);
+        this.rows.add(row);
+        this.totalRows = this.rows.size();
+        this.totalAmount = this.totalAmount.add(row.getAmount());
+    }
+
+    public boolean isPosted() {
+        return STATUS_POSTED.equals(this.status);
+    }
+
+    /** Under way. Set before the work starts, so a second press finds it already running. */
+    public boolean isPosting() {
+        return STATUS_POSTING.equals(this.status);
+    }
+
+    public void markPosting() {
+        this.status = STATUS_POSTING;
+        this.rowsPosted = 0;
+        this.failureReason = null;
+    }
+
+    public void recordProgress(final int posted) {
+        this.rowsPosted = posted;
+    }
+
+    public void markPosted(final LocalDate postedOnDate) {
+        this.status = STATUS_POSTED;
+        this.postedOnDate = postedOnDate;
+        this.rowsPosted = this.totalRows;
+        this.failureReason = null;
+    }
+
+    /**
+     * Records why a run stopped, and leaves it able to be run again.
+     *
+     * Nothing it had credited stands: the whole run is one transaction, so a failure takes all of it
+     * back. That is the point - the branch is left with a run that plainly did not happen rather than
+     * one it has to reconcile by hand.
+     */
+    public void markFailed(final String reason) {
+        this.status = STATUS_FAILED;
+        this.failureReason = reason == null ? "Unknown error" : reason.substring(0, Math.min(reason.length(), 500));
+    }
+
+    private static final String STATUS_POSTED = "POSTED";
+    private static final String STATUS_POSTING = "POSTING";
+    private static final String STATUS_FAILED = "FAILED";
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/domain/BatchRunRow.java

@@ -0,0 +1,130 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractPersistableCustom;
+
+/**
+ * One previewed/posted line of a {@link BatchRun}: for an interest job, one Party's interest; for a
+ * commission job, one Agent's commission on their collected volume (partyId is null there).
+ *
+ * {@code amount} is always what actually gets applied. The remaining figures record how that amount
+ * was arrived at, which is what the Agent Commission Statement prints and what an agent querying a
+ * payout needs to see. They are stored rather than recomputed on demand because the inputs move: the
+ * slab chart can be corrected and the standing deductions change, so a later recomputation would not
+ * reproduce the figure that was actually paid.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_batch_run_row")
+public class BatchRunRow extends AbstractPersistableCustom<Long> {
+
+    @ManyToOne
+    @JoinColumn(name = "batch_run_id", nullable = false)
+    private BatchRun batchRun;
+
+    @Column(name = "party_id")
+    private Long partyId;
+
+    @Column(name = "agent_id", nullable = false)
+    private Long agentId;
+
+    /** What this row applies: interest accrued or posted, or commission net of every deduction. */
+    @Column(name = "amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal amount;
+
+    /**
+     * What the rate was applied to: the collection volume for commission, or the daily product
+     * (balance summed over the days it was held) for interest.
+     */
+    @Column(name = "base_amount", scale = 6, precision = 19)
+    private BigDecimal baseAmount;
+
+    @Column(name = "rate_percent", scale = 6, precision = 19)
+    private BigDecimal ratePercent;
+
+    /** Before deductions. Equal to {@code amount} on rows that have none. */
+    @Column(name = "gross_amount", scale = 6, precision = 19)
+    private BigDecimal grossAmount;
+
+    @Column(name = "tds_amount", scale = 6, precision = 19)
+    private BigDecimal tdsAmount;
+
+    @Column(name = "deduction_amount", scale = 6, precision = 19)
+    private BigDecimal deductionAmount;
+
+    @Column(name = "from_date")
+    private LocalDate fromDate;
+
+    @Column(name = "to_date")
+    private LocalDate toDate;
+
+    protected BatchRunRow() {
+        //
+    }
+
+    private BatchRunRow(final Long partyId, final Long agentId, final BigDecimal amount, final BigDecimal baseAmount,
+            final BigDecimal ratePercent, final BigDecimal grossAmount, final BigDecimal tdsAmount, final BigDecimal deductionAmount,
+            final LocalDate fromDate, final LocalDate toDate) {
+        this.partyId = partyId;
+        this.agentId = agentId;
+        this.amount = amount;
+        this.baseAmount = baseAmount;
+        this.ratePercent = ratePercent;
+        this.grossAmount = grossAmount;
+        this.tdsAmount = tdsAmount;
+        this.deductionAmount = deductionAmount;
+        this.fromDate = fromDate;
+        this.toDate = toDate;
+    }
+
+    /** Interest earned on a Party's balance over the days it was held. Nothing is deducted from it. */
+    public static BatchRunRow forInterest(final Long partyId, final Long agentId, final BigDecimal amount,
+            final BigDecimal dailyProduct, final BigDecimal ratePercent, final LocalDate fromDate, final LocalDate toDate) {
+        return new BatchRunRow(partyId, agentId, amount, dailyProduct, ratePercent, amount, null, null, fromDate, toDate);
+    }
+
+    /** An Agent's commission on their collection volume, net of TDS and the standing deductions. */
+    public static BatchRunRow forCommission(final Long agentId, final BigDecimal netAmount, final BigDecimal collectionVolume,
+            final BigDecimal ratePercent, final BigDecimal grossAmount, final BigDecimal tdsAmount, final BigDecimal deductionAmount,
+            final LocalDate fromDate, final LocalDate toDate) {
+        return new BatchRunRow(null, agentId, netAmount, collectionVolume, ratePercent, grossAmount, tdsAmount, deductionAmount,
+                fromDate, toDate);
+    }
+
+    /**
+     * A posting row: it moves an amount that a prior calculation run already worked out, so there is
+     * no rate or base to record against it - the run that calculated it holds those.
+     */
+    public static BatchRunRow forPosting(final Long partyId, final Long agentId, final BigDecimal amount, final LocalDate asOnDate) {
+        return new BatchRunRow(partyId, agentId, amount, null, null, amount, null, null, asOnDate, asOnDate);
+    }
+
+    void setBatchRun(final BatchRun batchRun) {
+        this.batchRun = batchRun;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/exception/BatchRunAlreadyPostedException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when Post is attempted on a batch run that has already been posted - a run applies once,
+ * matching the calculate-then-post safety control (never re-post the same preview).
+ */
+public class BatchRunAlreadyPostedException extends AbstractPlatformDomainRuleException {
+
+    public BatchRunAlreadyPostedException(final Long batchRunId) {
+        super("error.msg.ddsbatchrun.already.posted", "DDS batch run " + batchRunId + " has already been posted", batchRunId);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/exception/BatchRunNotFoundException.java

@@ -0,0 +1,28 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+
+public class BatchRunNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public BatchRunNotFoundException(final Long id) {
+        super("error.msg.ddsbatchrun.id.invalid", "DDS batch run with identifier " + id + " does not exist", id);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/batch/exception/NoCommissionSlabException.java

@@ -0,0 +1,41 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.batch.exception;
+
+import java.math.BigDecimal;
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an agent's collection volume falls in a gap in the commission chart, so there is no rate
+ * to pay them at.
+ *
+ * The run stops rather than skipping the agent. A gap is a mistake in the chart, and an agent who
+ * worked all month reading as earning nothing looks exactly like an agent who collected nothing - the
+ * one failure nobody would query until the agent complained. Naming the agent and the amount that
+ * found no slab points straight at the range that needs adding.
+ */
+public class NoCommissionSlabException extends AbstractPlatformDomainRuleException {
+
+    public NoCommissionSlabException(final String agentCode, final BigDecimal collectionVolume) {
+        super("error.msg.ddsbatchrun.no.commission.slab",
+                "No commission slab covers " + collectionVolume.toPlainString() + ", the collection volume for agent " + agentCode
+                        + ". Add a slab covering this amount to the Commission Slab Master and run the calculation again.",
+                agentCode, collectionVolume);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/calculation/DdsCommissionCalculation.java

@@ -0,0 +1,85 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.calculation;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+/**
+ * What a collection agent has earned on a period's collections, and what is left after deductions.
+ *
+ * <pre>
+ *   gross       the slab's percentage of everything collected
+ *   tds         withheld from the gross, when the agent is liable for it
+ *   deductions  the four standing amounts the bank recovers from them
+ *   net         what the agent is actually paid
+ * </pre>
+ *
+ * Every figure is kept, not just the net: an agent asking why their commission was short needs the
+ * whole breakdown, and a later change to the slab must not alter what was already paid.
+ *
+ * <p>
+ * Kept apart from the job that runs it so the sum can be checked on its own.
+ */
+public record DdsCommissionCalculation(BigDecimal collectionVolume, BigDecimal ratePercent, BigDecimal gross, BigDecimal tds,
+        BigDecimal deductions, BigDecimal net) {
+
+    private static final BigDecimal HUNDRED = BigDecimal.valueOf(100);
+    private static final int MONEY_SCALE = 2;
+
+    /**
+     * Works out a period's commission.
+     *
+     * @param collectionVolume
+     *            everything the agent collected in the period.
+     * @param ratePercent
+     *            the matching slab's percentage.
+     * @param tdsApplicable
+     *            whether tax is withheld from this agent at all.
+     * @param tdsPercent
+     *            the rate withheld when it is.
+     * @param deductions
+     *            the standing amounts the bank recovers - see {@code Agent.totalDeductions()}.
+     */
+    public static DdsCommissionCalculation of(final BigDecimal collectionVolume, final BigDecimal ratePercent,
+            final boolean tdsApplicable, final BigDecimal tdsPercent, final BigDecimal deductions) {
+
+        final BigDecimal volume = collectionVolume == null ? BigDecimal.ZERO : collectionVolume;
+        final BigDecimal rate = ratePercent == null ? BigDecimal.ZERO : ratePercent;
+        final BigDecimal recovered = deductions == null ? BigDecimal.ZERO : deductions;
+
+        final BigDecimal gross = volume.multiply(rate).divide(HUNDRED, MONEY_SCALE, RoundingMode.HALF_UP);
+        final BigDecimal withheld = tdsApplicable && tdsPercent != null
+                ? gross.multiply(tdsPercent).divide(HUNDRED, MONEY_SCALE, RoundingMode.HALF_UP)
+                : BigDecimal.ZERO;
+
+        return new DdsCommissionCalculation(volume, rate, gross, withheld, recovered, gross.subtract(withheld).subtract(recovered));
+    }
+
+    /**
+     * Whether there is anything to pay.
+     *
+     * The deductions can swallow a period's commission entirely. Nothing is owed then, and the agent
+     * is not put into debt over it - the deductions are standing figures the bank adjusts, not a
+     * balance a commission run is entitled to carry forward.
+     */
+    public boolean isPayable() {
+        return this.net.compareTo(BigDecimal.ZERO) > 0;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/calculation/DdsInterestCalculation.java

@@ -0,0 +1,126 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.calculation;
+
+import java.math.BigDecimal;
+import java.math.MathContext;
+import java.math.RoundingMode;
+import java.time.LocalDate;
+import java.time.temporal.ChronoUnit;
+import java.util.List;
+
+/**
+ * What a DDS account has earned over a period.
+ *
+ * Interest is on the <em>daily product</em>: the balance summed over the days it was actually held.
+ * A customer paying in daily holds each instalment for a different length of time, so interest on
+ * the closing balance for the whole period would pay them for money they had not yet deposited -
+ * roughly double what they are owed, which is what this replaced.
+ *
+ * This is the same basis {@code Party.calculateMaturityAmount()} quotes at opening, so what the
+ * interest runs add up to over a term matches the figure the customer was promised.
+ *
+ * <p>
+ * Kept apart from the job that runs it so the sum can be checked on its own. It reads nothing and
+ * writes nothing - given the same movements it always answers the same, which is what makes it
+ * worth testing.
+ */
+public final class DdsInterestCalculation {
+
+    /** Wide enough that the intermediate division never loses precision before the final rounding. */
+    private static final MathContext MATH_CONTEXT = new MathContext(19, RoundingMode.HALF_UP);
+
+    private static final BigDecimal HUNDRED = BigDecimal.valueOf(100);
+    private static final BigDecimal DAYS_IN_YEAR = BigDecimal.valueOf(365);
+    private static final int MONEY_SCALE = 2;
+
+    private DdsInterestCalculation() {}
+
+    /**
+     * One movement on the account: a collection is positive, a payout negative.
+     *
+     * A plain pair rather than the transaction itself, so this sum has no opinion about how
+     * transactions are stored and can be checked with a handful of literals.
+     */
+    public record Movement(LocalDate date, BigDecimal signedAmount) {}
+
+    /**
+     * The balance summed over the days it was held, between {@code from} (exclusive) and {@code to}
+     * (inclusive).
+     *
+     * @param openingBalance
+     *            what the account held before any of these movements.
+     * @param movements
+     *            every movement up to the end of the period, oldest first. Anything dated on or
+     *            before {@code from} has already happened and makes up the balance this period opens
+     *            with rather than a movement within it.
+     */
+    public static BigDecimal dailyProduct(final BigDecimal openingBalance, final List<Movement> movements, final LocalDate from,
+            final LocalDate to) {
+
+        BigDecimal balance = openingBalance == null ? BigDecimal.ZERO : openingBalance;
+        int index = 0;
+        while (index < movements.size() && !movements.get(index).date().isAfter(from)) {
+            balance = balance.add(movements.get(index).signedAmount());
+            index++;
+        }
+
+        BigDecimal product = BigDecimal.ZERO;
+        LocalDate cursor = from;
+
+        while (index < movements.size()) {
+            final LocalDate movementDate = movements.get(index).date();
+            if (movementDate.isAfter(to)) {
+                break;
+            }
+
+            // The untouched days between the last movement and this one, at the balance they stood at.
+            final long daysAtOpeningBalance = ChronoUnit.DAYS.between(cursor, movementDate) - 1;
+            if (daysAtOpeningBalance > 0) {
+                product = product.add(balance.multiply(BigDecimal.valueOf(daysAtOpeningBalance)));
+            }
+
+            // Apply every movement dated that day before counting the day itself, so a deposit earns
+            // from the day it was made.
+            while (index < movements.size() && movementDate.equals(movements.get(index).date())) {
+                balance = balance.add(movements.get(index).signedAmount());
+                index++;
+            }
+            product = product.add(balance);
+            cursor = movementDate;
+        }
+
+        final long remainingDays = ChronoUnit.DAYS.between(cursor, to);
+        if (remainingDays > 0) {
+            product = product.add(balance.multiply(BigDecimal.valueOf(remainingDays)));
+        }
+
+        return product;
+    }
+
+    /** Simple interest on a daily product at an annual rate, rounded to paise. */
+    public static BigDecimal interestOn(final BigDecimal dailyProduct, final BigDecimal ratePercent) {
+        if (dailyProduct == null || ratePercent == null || dailyProduct.compareTo(BigDecimal.ZERO) <= 0
+                || ratePercent.compareTo(BigDecimal.ZERO) <= 0) {
+            return BigDecimal.ZERO.setScale(MONEY_SCALE);
+        }
+        return dailyProduct.multiply(ratePercent).divide(HUNDRED.multiply(DAYS_IN_YEAR), MATH_CONTEXT).setScale(MONEY_SCALE,
+                RoundingMode.HALF_UP);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/calculation/DdsSchedule.java

@@ -0,0 +1,117 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.calculation;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.time.LocalDate;
+import java.time.temporal.ChronoUnit;
+
+/**
+ * Where a daily deposit account stands against the instalments it owes.
+ *
+ * The bank's rule has two sides and they are not symmetrical. A customer may run ahead, but only a few
+ * days - the scheme is a habit of saving daily, not a deposit paid in one go. A customer may fall
+ * behind and catch up, but only within a short window; instalments older than that are skipped, and
+ * skipped means gone - the agent does not go back for them, and the account matures on what was
+ * actually paid.
+ *
+ * So a shortfall is split rather than shown as one figure. What can still be collected is worth a
+ * clerk chasing today; what has passed the window is not, and showing them together would have the
+ * clerk asking for money the bank has already written off.
+ *
+ * Kept here, outside either service, because the screen that shows these figures and the check that
+ * refuses a collection exceeding them have to agree. Two copies would drift, and the day they did the
+ * screen would quote a customer an amount the server then refused.
+ *
+ * @param expected what should have been collected by the day this was worked out
+ * @param advance signed: positive is paid ahead, negative is behind
+ * @param advanceDays whole instalments covered ahead - a part-paid day does not count
+ * @param arrearsDays whole or part instalments behind
+ * @param recoverable the part of a shortfall still inside the catch-up window
+ * @param skippedDays instalments past that window
+ * @param skipped what those come to
+ */
+public record DdsSchedule(BigDecimal expected, BigDecimal advance, int advanceDays, int arrearsDays, BigDecimal recoverable,
+        int skippedDays, BigDecimal skipped) {
+
+    /**
+     * How far behind an account may fall and still be caught up. Past this the instalments are
+     * skipped - the agent does not go back for them and the customer matures on less.
+     */
+    public static final int CATCH_UP_DAYS = 3;
+
+    /**
+     * The most a customer may pay ahead, so a scheme is not simply prepaid into a lump deposit. A few
+     * days is the bank's allowance for someone going away or paid weekly.
+     */
+    public static final int MAX_ADVANCE_DAYS = 5;
+
+    private static final DdsSchedule NOTHING_DUE = new DdsSchedule(BigDecimal.ZERO, BigDecimal.ZERO, 0, 0, BigDecimal.ZERO, 0,
+            BigDecimal.ZERO);
+
+    /**
+     * How many instalments should have been paid by the given day.
+     *
+     * The first falls on the opening day itself - the same day the maturity figure starts counting
+     * from, so the two agree - and the count stops at the term's own length, so a matured account does
+     * not keep falling further behind.
+     */
+    public static int instalmentsDue(final LocalDate openingDate, final Integer termDays, final LocalDate on) {
+        if (openingDate == null || termDays == null || termDays <= 0 || on == null) {
+            return 0;
+        }
+        final long elapsed = ChronoUnit.DAYS.between(openingDate, on) + 1;
+        return (int) Math.max(0, Math.min(termDays, elapsed));
+    }
+
+    public static DdsSchedule of(final BigDecimal daily, final int instalmentsDue, final BigDecimal collected) {
+        if (daily == null || daily.compareTo(BigDecimal.ZERO) <= 0) {
+            // Nothing is due daily, so there is no schedule to be ahead or behind of.
+            return NOTHING_DUE;
+        }
+
+        final BigDecimal paid = collected == null ? BigDecimal.ZERO : collected;
+        final BigDecimal expected = daily.multiply(BigDecimal.valueOf(instalmentsDue));
+        final BigDecimal advance = paid.subtract(expected);
+
+        if (advance.compareTo(BigDecimal.ZERO) >= 0) {
+            // Ahead. Only whole instalments count as days covered - a customer eighty rupees into a
+            // hundred-rupee day still owes today, and the agent should still call.
+            final int daysCovered = advance.divideToIntegralValue(daily).intValue();
+            return new DdsSchedule(expected, advance, daysCovered, 0, BigDecimal.ZERO, 0, BigDecimal.ZERO);
+        }
+
+        // Behind. A part-paid day counts as a day behind for the same reason.
+        final BigDecimal shortfall = advance.negate();
+        final int daysBehind = shortfall.divide(daily, 0, RoundingMode.CEILING).intValue();
+        final BigDecimal window = daily.multiply(BigDecimal.valueOf(CATCH_UP_DAYS));
+        final BigDecimal recoverable = shortfall.min(window);
+        return new DdsSchedule(expected, advance, 0, daysBehind, recoverable, Math.max(0, daysBehind - CATCH_UP_DAYS),
+                shortfall.subtract(recoverable));
+    }
+
+    /** Whole instalments a customer may still pay off, which is what the arrears option may offer. */
+    public int recoverableDays(final BigDecimal daily) {
+        if (daily == null || daily.compareTo(BigDecimal.ZERO) <= 0) {
+            return 0;
+        }
+        return this.recoverable.divideToIntegralValue(daily).intValue();
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/collection/data/AgentCollectionSummaryData.java

@@ -0,0 +1,53 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.collection.data;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+import lombok.Builder;
+import lombok.Data;
+
+/**
+ * An agent's day, as the clerk sees it when the agent walks up to the counter.
+ *
+ * The figure that matters is {@code expectedAmount}: what the agent's own entries add up to, and so
+ * what should be in their bag. It is given as a total beside the lines it came from, because a clerk
+ * who is short counts the lines to find out where.
+ */
+@Data
+@Builder
+public class AgentCollectionSummaryData {
+
+    private final Long agentId;
+    private final String agentCode;
+    private final String agentName;
+    private final LocalDate entryDate;
+
+    private final int pendingCount;
+
+    /** What the agent's outstanding entries add up to - the cash the branch should be handed. */
+    private final BigDecimal expectedAmount;
+
+    /** What has already been counted and posted for this agent on this date. */
+    private final int settledCount;
+    private final BigDecimal settledAmount;
+
+    private final List<CollectionEntryData> entries;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/collection/data/CollectionEntryData.java

@@ -0,0 +1,66 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.collection.data;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Builder;
+import lombok.Data;
+
+/**
+ * One written-down collection, as the agent's screen and the clerk's settlement list show it.
+ *
+ * Carries the party's code, name and balance beside the amount, because both readers are checking
+ * the line against a person rather than an id - the agent against the customer they just left, the
+ * clerk against the passbook in front of them.
+ */
+@Data
+@Builder
+public class CollectionEntryData {
+
+    private final Long id;
+
+    private final Long agentId;
+    private final String agentCode;
+    private final String agentName;
+
+    private final Long partyId;
+    private final String partyCode;
+    private final String partyName;
+
+    /** The account's balance as it stands now - before this entry, which has not been posted. */
+    private final BigDecimal partyBalance;
+
+    /** What this scheme takes each day, so an amount that is not a day's instalment stands out. */
+    private final BigDecimal dailyDepositAmount;
+
+    private final LocalDate entryDate;
+    private final BigDecimal amount;
+    private final String transactionMode;
+    private final String chequeNo;
+    private final String tokenNo;
+    private final String description;
+
+    private final String status;
+    private final LocalDate settledOn;
+    private final Long partyTransactionId;
+    /** Days paid ahead, or days of arrears cleared - empty on an ordinary day's collection. */
+    private final Integer advanceDays;
+    private final Integer arrearsDays;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/collection/domain/CollectionEntry.java

@@ -0,0 +1,174 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.collection.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+import org.apache.fineract.organisation.agent.domain.Agent;
+import org.apache.fineract.portfolio.dds.party.domain.Party;
+
+/**
+ * One line an agent wrote down on their round: this customer, this much, in this form.
+ *
+ * It is not a transaction and deliberately reads nothing like one. No balance is carried on it, no
+ * ledger entry stands behind it, and no report of the bank's position counts it. It says only what
+ * the agent says they collected - the bank's own record of it begins when a clerk has counted the
+ * cash and confirmed the day's entries, and what that writes is an ordinary
+ * {@code m_dds_party_transaction} row.
+ *
+ * The distinction is the whole point of the table. Credited on the spot, the books showed customers
+ * paid in notes the branch had never held, and there was nothing to count the agent's bag against
+ * when they arrived. Held here, the agent's word and the bank's books stay separate until somebody
+ * puts them side by side.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_collection_entry")
+public class CollectionEntry extends AbstractAuditableCustom {
+
+    /** Waiting for a clerk to count the cash behind it. */
+    public static final String PENDING = "PENDING";
+
+    /** Counted, posted, and now standing behind a real transaction. */
+    public static final String SETTLED = "SETTLED";
+
+    /** Withdrawn before it was ever posted - a wrong line the agent took back. */
+    public static final String CANCELLED = "CANCELLED";
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    @ManyToOne
+    @JoinColumn(name = "party_id", nullable = false)
+    private Party party;
+
+    /**
+     * The day the money changed hands, which is the agent's day and not the branch's. A round
+     * collected on Friday and brought in on Monday is still Friday's collection, and the customer's
+     * statement has to say so.
+     */
+    @Column(name = "entry_date", nullable = false)
+    private LocalDate entryDate;
+
+    @Column(name = "amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal amount;
+
+    @Column(name = "transaction_mode", length = 20, nullable = false)
+    private String transactionMode;
+
+    @Column(name = "cheque_no", length = 50)
+    private String chequeNo;
+
+    @Column(name = "token_no", length = 50)
+    private String tokenNo;
+
+    @Column(name = "description", length = 200)
+    private String description;
+
+    @Column(name = "status", length = 20, nullable = false)
+    private String status;
+
+    @Column(name = "settled_on")
+    private LocalDate settledOn;
+
+    /**
+     * The transaction this entry became, once it was posted.
+     *
+     * Held as a plain id rather than a mapped association: this table is the paper the bank checked
+     * against, not part of the ledger, and a link that pulled a transaction in whenever an entry was
+     * read would make the two look like halves of one thing. Anyone who needs the transaction can
+     * fetch it; most callers only need to know there is one.
+     */
+    @Column(name = "party_transaction_id")
+    private Long partyTransactionId;
+
+    /**
+     * The application of the cashier's DDS receipts that settled this entry, when it was settled that
+     * way - see 0517, which records which vouchers it used. A plain id for the same reason as the
+     * transaction.
+     */
+    @Column(name = "receipt_application_id")
+    private Long receiptApplicationId;
+
+    /** Days paid ahead, or days of arrears cleared - see 0520. Both empty on an ordinary day's collection. */
+    @Column(name = "advance_days")
+    private Integer advanceDays;
+
+    @Column(name = "arrears_days")
+    private Integer arrearsDays;
+
+    protected CollectionEntry() {
+        //
+    }
+
+    public CollectionEntry(final Agent agent, final Party party, final LocalDate entryDate, final BigDecimal amount,
+            final String transactionMode, final String chequeNo, final String tokenNo, final String description) {
+        this.agent = agent;
+        this.party = party;
+        this.entryDate = entryDate;
+        this.amount = amount;
+        this.transactionMode = transactionMode;
+        this.chequeNo = chequeNo;
+        this.tokenNo = tokenNo;
+        this.description = description;
+        this.status = PENDING;
+    }
+
+    /** Records what the collection covers beyond today, once its amount has been checked against it. */
+    public void covering(final Integer advanceDays, final Integer arrearsDays) {
+        this.advanceDays = advanceDays;
+        this.arrearsDays = arrearsDays;
+    }
+
+    public boolean isPending() {
+        return PENDING.equals(this.status);
+    }
+
+    /**
+     * Records that this entry has been counted and posted, and what it became.
+     *
+     * The transaction's id is kept so the two can always be put back together - a clerk asked six
+     * months later which entry a credit came from has an answer, rather than a matching exercise on
+     * date and amount.
+     */
+    public void markSettled(final LocalDate settledOn, final Long partyTransactionId) {
+        this.status = SETTLED;
+        this.settledOn = settledOn;
+        this.partyTransactionId = partyTransactionId;
+    }
+
+    /** Settled against the cashier's receipts: the same as {@link #markSettled}, and which application did it. */
+    public void markSettledByReceipt(final LocalDate settledOn, final Long partyTransactionId, final Long receiptApplicationId) {
+        markSettled(settledOn, partyTransactionId);
+        this.receiptApplicationId = receiptApplicationId;
+    }
+
+    /** Withdraws a line that was never posted. Kept, not deleted - the agent wrote it, so it stands. */
+    public void markCancelled() {
+        this.status = CANCELLED;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/collection/exception/CollectionEntryNotFoundException.java

@@ -0,0 +1,28 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.collection.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+
+public class CollectionEntryNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public CollectionEntryNotFoundException(final Long entryId) {
+        super("error.msg.dds.collection.entry.not.found", "Collection entry " + entryId + " does not exist", entryId);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/collection/exception/CollectionEntryNotPendingException.java

@@ -0,0 +1,37 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.collection.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a written-down collection is taken back after it has already been settled.
+ *
+ * By then it is not a note any more - a customer has been credited and an agent's cash recorded
+ * against it. Withdrawing it here would leave the note cancelled and the credit standing, which is
+ * the one state nobody could reconcile. A posted collection is undone the way any posting is: with
+ * an entry the other way, on the ledger, where it can be seen.
+ */
+public class CollectionEntryNotPendingException extends AbstractPlatformDomainRuleException {
+
+    public CollectionEntryNotPendingException(final Long entryId, final String status) {
+        super("error.msg.dds.collection.entry.not.pending",
+                "Collection entry " + entryId + " is " + status.toLowerCase() + " and can no longer be cancelled", entryId, status);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/collection/exception/NothingToSettleException.java

@@ -0,0 +1,36 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.collection.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a settlement is asked for and the agent has nothing outstanding on that date.
+ *
+ * Said plainly rather than passed off as a settlement of nothing, because the clerk is standing at
+ * the counter with an agent in front of them: either they have the wrong date, or the round has been
+ * settled already, and both are worth knowing before the cash is taken.
+ */
+public class NothingToSettleException extends AbstractPlatformDomainRuleException {
+
+    public NothingToSettleException(final String agentCode, final String entryDate) {
+        super("error.msg.dds.collection.nothing.to.settle",
+                "Agent " + agentCode + " has no collection entries outstanding for " + entryDate, agentCode, entryDate);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/data/PartyData.java

@@ -0,0 +1,182 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.Collection;
+import lombok.Builder;
+import lombok.Getter;
+
+/**
+ * Immutable data object representing a DDS Party (customer scheme account), including its nominees.
+ * Built via the Lombok builder rather than a long positional constructor - the field count here makes
+ * positional args unreadable and error-prone to keep in sync.
+ */
+@Getter
+@Builder(toBuilder = true)
+public final class PartyData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long clientId;
+    private final String clientName;
+    private final Long agentId;
+    private final String agentCode;
+    private final String agentName;
+    /** The branch this account belongs to - its own, not the collecting agent's. */
+    private final Long officeId;
+    private final String officeName;
+    /**
+     * The customer's real deposit account, opened when the party was created.
+     *
+     * The id alone was carried here before, which is a number only the database means anything by -
+     * a screen showing "36" tells an officer nothing. The account's own number, product, status and
+     * balance are read from the account itself, so what a party shows is what the bank's books say
+     * rather than a second copy that can drift. All four are null for a party opened before DDS
+     * began opening real accounts, and that is worth showing plainly rather than hiding.
+     */
+    private final Long savingsAccountId;
+    private final String savingsAccountNo;
+    private final String savingsProductName;
+    private final String savingsAccountStatus;
+    private final BigDecimal savingsAccountBalance;
+    /**
+     * What on this account is pledged against a loan and cannot leave.
+     *
+     * Shown beside the balance on the closure list because a deposit standing as security is owed but
+     * not payable, and a clerk who reads only the balance would try to pay it and be refused.
+     */
+    private final BigDecimal amountHeldUnderLien;
+    private final String subType;
+    /**
+     * The account type's description, resolved from the DDS Account Type master that {@code subType}
+     * holds the code of - so callers can show the scheme by the name officers know it by without
+     * fetching the master separately.
+     */
+    private final String subTypeDescription;
+    private final String partyCode;
+    /** The DDS account's own number. */
+    private final String accountNo;
+    private final String lastAccount;
+    private final Boolean nominal;
+    private final String aadharNo;
+    private final String partyName;
+    private final String partyName1;
+    private final String address1;
+    private final String address2;
+    private final String address3;
+    private final String city;
+    private final String pincode;
+    private final String gender;
+    private final String panCardNo;
+    private final String telephone;
+    private final String mobileNoSms;
+    private final String operation;
+    private final LocalDate birthDate;
+    private final String occupation;
+    private final String risk;
+    private final String ckycId;
+    private final String adultMinor;
+    private final LocalDate minorDate;
+
+    /**
+     * The day a minor account holder comes of age, and whether it has passed.
+     *
+     * Worked out from the birth date rather than taken from {@code minorDate}, which is typed in by
+     * hand and has never been filled on any record. Null on an adult's account.
+     *
+     * The guardian's authority to operate the account ends on that day, so the branch has to take
+     * fresh KYC, a signature and a new mandate from the customer themselves. Nothing acts on this
+     * yet - whether the account should also be restricted until that is done is the bank's rule, and
+     * blocking one wrongly would strand a customer's money. It is carried here so the day stops
+     * passing unnoticed, which is what happened before.
+     */
+    private final LocalDate majorOn;
+    private final boolean minorTurnedMajor;
+    private final Long guardianClientId;
+    private final String minAccountOpt;
+    private final String relation;
+    private final LocalDate openingDate;
+    private final Integer month;
+    private final LocalDate maturityDate;
+    private final LocalDate reopenDate;
+    private final BigDecimal depositAmount;
+    private final BigDecimal dailyDepositAmount;
+    private final Integer days;
+    private final String ledgerNo;
+    private final BigDecimal maturityAmount;
+    private final BigDecimal interestRate;
+    private final String withdrawType;
+    private final Boolean od1Flag;
+    private final Boolean od2Flag;
+    private final Boolean lien;
+    /** Why the money is held - null when it is not. */
+    private final String lienReason;
+    private final LocalDate payDate;
+    private final BigDecimal paymentAmount;
+    private final BigDecimal currentBalance;
+    private final BigDecimal openingBalance;
+
+    /**
+     * Where this account stands against the instalments it should have paid by today.
+     *
+     * A daily scheme is a promise to pay a fixed sum every day, and the only figure the screen used to
+     * show was the running balance - which says how much has been paid but not whether it was paid on
+     * time. A customer eleven instalments behind and one who is four ahead can hold the same balance.
+     *
+     * {@code advanceAmount} is signed: positive is paid ahead, negative is behind. The rest of these
+     * read it in the bank's own terms - how many days that comes to, how much of a shortfall can still
+     * be recovered within the catch-up window, and how much has fallen outside it and is gone.
+     */
+    private final Integer instalmentsDue;
+    private final BigDecimal expectedToDate;
+    private final BigDecimal collectedToDate;
+    private final BigDecimal advanceAmount;
+    private final Integer advanceDays;
+    private final Integer arrearsDays;
+    private final BigDecimal recoverableAmount;
+    /** Instalments now past the catch-up window. These are not collected again - they are lost. */
+    private final Integer skippedDays;
+    private final BigDecimal skippedAmount;
+    private final Boolean isSmsActive;
+    private final Boolean isEmailActive;
+    /** Interest worked out but not yet credited, and how far it is calculated through. */
+    private final BigDecimal interestCalc;
+    private final LocalDate interestDate;
+
+    /** The same pair for the OD interest stream, which runs and posts independently. */
+    private final BigDecimal odInterestCalc;
+    private final LocalDate odInterestDate;
+    private final String spDescription;
+    private final String freezeCode;
+    private final String advCode;
+    private final String creditToBranch;
+    private final String creditToAccountType;
+    private final String creditToAccount;
+    private final Boolean nomineeApplicable;
+    private final String nomineeSplitMode;
+    private final String status;
+    private final LocalDate closeDate;
+    private final Collection<PartyNomineeData> nominees;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/data/PartyNomineeData.java

@@ -0,0 +1,69 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+
+@Getter
+public final class PartyNomineeData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final LocalDate nominationDate;
+    private final String name;
+    private final String mobileNo;
+    private final LocalDate birthDate;
+    private final Boolean minor;
+    private final String relation;
+    private final String gender;
+    private final String guardianName;
+    /** Null under a Sequence split, where the order the nominees are paid in is the entitlement. */
+    private final BigDecimal sharePercent;
+    /** Null under a Percentage split, where everyone is paid at once and there is no first. */
+    private final Integer sequenceNo;
+
+    public static PartyNomineeData instance(final Long id, final LocalDate nominationDate, final String name, final String mobileNo,
+            final LocalDate birthDate, final Boolean minor, final String relation, final String gender, final String guardianName,
+            final BigDecimal sharePercent, final Integer sequenceNo) {
+        return new PartyNomineeData(id, nominationDate, name, mobileNo, birthDate, minor, relation, gender, guardianName, sharePercent,
+                sequenceNo);
+    }
+
+    private PartyNomineeData(final Long id, final LocalDate nominationDate, final String name, final String mobileNo,
+            final LocalDate birthDate, final Boolean minor, final String relation, final String gender, final String guardianName,
+            final BigDecimal sharePercent, final Integer sequenceNo) {
+        this.id = id;
+        this.nominationDate = nominationDate;
+        this.name = name;
+        this.mobileNo = mobileNo;
+        this.birthDate = birthDate;
+        this.minor = minor;
+        this.relation = relation;
+        this.gender = gender;
+        this.guardianName = guardianName;
+        this.sharePercent = sharePercent;
+        this.sequenceNo = sequenceNo;
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/domain/Party.java

@@ -0,0 +1,791 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.domain;
+
+import jakarta.persistence.CascadeType;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.OneToMany;
+import jakarta.persistence.OrderBy;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+import java.math.BigDecimal;
+import java.math.MathContext;
+import java.math.RoundingMode;
+import java.time.LocalDate;
+import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Consumer;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+import org.apache.fineract.organisation.agent.domain.Agent;
+import org.apache.fineract.organisation.office.domain.Office;
+import org.apache.fineract.portfolio.client.domain.Client;
+
+/**
+ * A DDS Party - the customer's daily-deposit scheme account, linked to the Agent who collects for it.
+ * Carries the scheme's KYC, terms and two-stage overdue flags, plus a nominee list.
+ *
+ * The underlying RD (recurring deposit) account this scheme conceptually reuses is not wired up yet -
+ * {@code savingsAccountId} is a nullable placeholder for that future linkage (see the DDS architecture
+ * decision to reuse the RD engine for the deposit half). Until then the scheme/balance fields below
+ * are this record's own, not mirrored from any m_savings_account row.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_party", uniqueConstraints = { @UniqueConstraint(columnNames = { "party_code" }, name = "party_code_UNIQUE") })
+public class Party extends AbstractAuditableCustom {
+
+    /** DDS accounts carry a flat interest rate unless the officer explicitly overrides it at creation. */
+    private static final BigDecimal DEFAULT_INTEREST_RATE = new BigDecimal("2");
+
+    /** Interest is quoted per annum, so the daily instalments are pro-rated over a year. */
+    private static final int DAYS_IN_YEAR = 365;
+
+    private static final MathContext MATH_CONTEXT = new MathContext(19, RoundingMode.HALF_UP);
+
+    public static final String STATUS_ACTIVE = "ACTIVE";
+    public static final String STATUS_CLOSED = "CLOSED";
+
+    @ManyToOne
+    @JoinColumn(name = "client_id", nullable = false)
+    private Client client;
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    /**
+     * The branch this account belongs to.
+     *
+     * Its own, not the collecting agent's. An agent working out of one branch can hold accounts for
+     * customers of another, and reassigning an account to a different agent should not move the
+     * customer's branch with it. Defaults to the agent's branch when the caller does not name one,
+     * which is what the account was read as before it had a branch of its own.
+     */
+    @ManyToOne
+    @JoinColumn(name = "office_id")
+    private Office office;
+
+    @Column(name = "savings_account_id")
+    private Long savingsAccountId;
+
+    @Column(name = "sub_type", length = 60, nullable = false)
+    private String subType;
+
+    @Column(name = "party_code", length = 20, nullable = false)
+    private String partyCode;
+
+    /** The DDS account's own number - see 0514. Given once the party has an id, and never changed. */
+    @Column(name = "account_no", length = 20)
+    private String accountNo;
+
+    @Column(name = "last_account", length = 50)
+    private String lastAccount;
+
+    @Column(name = "nominal", nullable = false)
+    private boolean nominal;
+
+    @Column(name = "aadhar_no", length = 20)
+    private String aadharNo;
+
+    @Column(name = "party_name", length = 100, nullable = false)
+    private String partyName;
+
+    @Column(name = "party_name1", length = 100)
+    private String partyName1;
+
+    @Column(name = "address1", length = 200, nullable = false)
+    private String address1;
+
+    @Column(name = "address2", length = 200)
+    private String address2;
+
+    @Column(name = "address3", length = 200)
+    private String address3;
+
+    @Column(name = "city", length = 100, nullable = false)
+    private String city;
+
+    @Column(name = "pincode", length = 20, nullable = false)
+    private String pincode;
+
+    @Column(name = "gender", length = 20)
+    private String gender;
+
+    @Column(name = "pan_card_no", length = 20)
+    private String panCardNo;
+
+    @Column(name = "telephone", length = 20)
+    private String telephone;
+
+    @Column(name = "mobile_no_sms", length = 20, nullable = false)
+    private String mobileNoSms;
+
+    @Column(name = "operation", length = 20, nullable = false)
+    private String operation;
+
+    @Column(name = "birth_date")
+    private LocalDate birthDate;
+
+    @Column(name = "occupation", length = 40)
+    private String occupation;
+
+    @Column(name = "risk", length = 20)
+    private String risk;
+
+    @Column(name = "ckyc_id", length = 40)
+    private String ckycId;
+
+    @Column(name = "adult_minor", length = 20, nullable = false)
+    private String adultMinor;
+
+    @Column(name = "minor_date")
+    private LocalDate minorDate;
+
+    @Column(name = "guardian_client_id")
+    private Long guardianClientId;
+
+    @Column(name = "min_account_opt", length = 40)
+    private String minAccountOpt;
+
+    @Column(name = "relation", length = 40)
+    private String relation;
+
+    @Column(name = "opening_date", nullable = false)
+    private LocalDate openingDate;
+
+    @Column(name = "months")
+    private Integer month;
+
+    @Column(name = "maturity_date")
+    private LocalDate maturityDate;
+
+    @Column(name = "reopen_date")
+    private LocalDate reopenDate;
+
+    @Column(name = "deposit_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal depositAmount;
+
+    @Column(name = "daily_deposit_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal dailyDepositAmount;
+
+    @Column(name = "days", nullable = false)
+    private Integer days;
+
+    @Column(name = "ledger_no", length = 40)
+    private String ledgerNo;
+
+    @Column(name = "maturity_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal maturityAmount;
+
+    @Column(name = "interest_rate", scale = 6, precision = 19, nullable = false)
+    private BigDecimal interestRate;
+
+    @Column(name = "withdraw_type", length = 20)
+    private String withdrawType;
+
+    @Column(name = "od1_flag", nullable = false)
+    private boolean od1Flag;
+
+    @Column(name = "od2_flag", nullable = false)
+    private boolean od2Flag;
+
+    /**
+     * Whether this account's money is being held, and so cannot leave.
+     *
+     * Deposits are unaffected - the agent collects as before and interest posts as before. What is
+     * refused is every way out: the maturity payout, an early closure, and a transfer to another
+     * party. A lien that stopped the collections would defeat the scheme it is securing.
+     */
+    @Column(name = "lien", nullable = false)
+    private boolean lien;
+
+    /**
+     * Why the money is held.
+     *
+     * The flag alone says an account is frozen and never says what for, which is how a held deposit
+     * outlives the loan it secured: months later nobody can tell whether it has been repaid, so
+     * nobody will release it and nobody can justify keeping it.
+     *
+     * It falls to a line of text because DDS and the loan module are not connected - nothing else in
+     * the system links a held deposit to the loan behind it.
+     */
+    @Column(name = "lien_reason", length = 200)
+    private String lienReason;
+
+    @Column(name = "pay_date")
+    private LocalDate payDate;
+
+    @Column(name = "payment_amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal paymentAmount;
+
+    @Column(name = "current_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal currentBalance;
+
+    @Column(name = "opening_balance", scale = 6, precision = 19, nullable = false)
+    private BigDecimal openingBalance;
+
+    @Column(name = "is_sms_active", nullable = false)
+    private boolean isSmsActive;
+
+    @Column(name = "is_email_active", nullable = false)
+    private boolean isEmailActive;
+
+    /** Interest worked out but not yet credited - the legacy screen's "Int.Calc". */
+    @Column(name = "interest_calc", scale = 6, precision = 19, nullable = false)
+    private BigDecimal interestCalc;
+
+    /** How far regular interest has been calculated through. */
+    @Column(name = "interest_date")
+    private LocalDate interestDate;
+
+    /**
+     * OD interest is a second stream over the same account, run and posted independently of regular
+     * interest, so it keeps its own accrued figure and through-date rather than sharing them.
+     */
+    @Column(name = "od_interest_calc", scale = 6, precision = 19, nullable = false)
+    private BigDecimal odInterestCalc;
+
+    @Column(name = "od_interest_date")
+    private LocalDate odInterestDate;
+
+    @Column(name = "sp_description", length = 500)
+    private String spDescription;
+
+    @Column(name = "freeze_code", length = 20, nullable = false)
+    private String freezeCode;
+
+    @Column(name = "adv_code", length = 40, nullable = false)
+    private String advCode;
+
+    @Column(name = "credit_to_branch", length = 100)
+    private String creditToBranch;
+
+    @Column(name = "credit_to_account_type", length = 100)
+    private String creditToAccountType;
+
+    @Column(name = "credit_to_account", length = 50)
+    private String creditToAccount;
+
+    @Column(name = "nominee_applicable", nullable = false)
+    private boolean nomineeApplicable;
+
+    @Column(name = "nominee_split_mode", length = 20)
+    private String nomineeSplitMode;
+
+    @Column(name = "status", length = 20, nullable = false)
+    private String status;
+
+    @Column(name = "close_date")
+    private LocalDate closeDate;
+
+    @OneToMany(mappedBy = "party", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+    @OrderBy("id")
+    private List<PartyNominee> nominees = new ArrayList<>();
+
+    protected Party() {
+        //
+    }
+
+    private Party(final Client client, final Agent agent, final Office office, final String partyCode, final JsonCommand command) {
+        this.client = client;
+        this.agent = agent;
+        this.office = office;
+        this.partyCode = partyCode;
+        this.subType = command.stringValueOfParameterNamed("subType");
+        this.lastAccount = command.stringValueOfParameterNamedAllowingNull("lastAccount");
+        this.nominal = command.booleanPrimitiveValueOfParameterNamed("nominal");
+        this.aadharNo = command.stringValueOfParameterNamedAllowingNull("aadharNo");
+        this.partyName = command.stringValueOfParameterNamed("partyName");
+        this.partyName1 = command.stringValueOfParameterNamedAllowingNull("partyName1");
+        this.address1 = command.stringValueOfParameterNamed("address1");
+        this.address2 = command.stringValueOfParameterNamedAllowingNull("address2");
+        this.address3 = command.stringValueOfParameterNamedAllowingNull("address3");
+        this.city = command.stringValueOfParameterNamed("city");
+        this.pincode = command.stringValueOfParameterNamed("pincode");
+        this.gender = command.stringValueOfParameterNamedAllowingNull("gender");
+        this.panCardNo = command.stringValueOfParameterNamedAllowingNull("panCardNo");
+        this.telephone = command.stringValueOfParameterNamedAllowingNull("telephone");
+        this.mobileNoSms = command.stringValueOfParameterNamed("mobileNoSms");
+        this.operation = command.stringValueOfParameterNamed("operation");
+        this.birthDate = command.localDateValueOfParameterNamed("birthDate");
+        this.occupation = command.stringValueOfParameterNamedAllowingNull("occupation");
+        this.risk = command.stringValueOfParameterNamedAllowingNull("risk");
+        this.ckycId = command.stringValueOfParameterNamedAllowingNull("ckycId");
+        this.adultMinor = command.stringValueOfParameterNamed("adultMinor");
+        this.minorDate = command.localDateValueOfParameterNamed("minorDate");
+        this.guardianClientId = command.longValueOfParameterNamed("guardianClientId");
+        this.minAccountOpt = command.stringValueOfParameterNamedAllowingNull("minAccountOpt");
+        this.relation = command.stringValueOfParameterNamedAllowingNull("relation");
+        this.openingDate = command.localDateValueOfParameterNamed("openingDate");
+        this.month = command.integerValueOfParameterNamedDefaultToNullIfZero("month");
+        // maturityDate and maturityAmount are not read from the request - recalculateTerm() below
+        // works both out from the opening date and the terms.
+        this.reopenDate = command.localDateValueOfParameterNamed("reopenDate");
+        this.depositAmount = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("depositAmount"));
+        this.dailyDepositAmount = command.bigDecimalValueOfParameterNamed("dailyDepositAmount");
+        this.days = command.integerValueOfParameterNamed("days");
+        this.ledgerNo = command.stringValueOfParameterNamedAllowingNull("ledgerNo");
+        this.maturityAmount = BigDecimal.ZERO;
+        this.interestRate = command.parameterExists("interestRate")
+                ? command.bigDecimalValueOfParameterNamed("interestRate")
+                : DEFAULT_INTEREST_RATE;
+        this.withdrawType = command.stringValueOfParameterNamedAllowingNull("withdrawType");
+        this.od1Flag = false;
+        this.od2Flag = false;
+        this.lien = command.booleanPrimitiveValueOfParameterNamed("lien");
+        this.lienReason = StringUtils.trimToNull(command.stringValueOfParameterNamedAllowingNull("lienReason"));
+        this.payDate = command.localDateValueOfParameterNamed("payDate");
+        this.paymentAmount = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("paymentAmount"));
+        this.openingBalance = orZero(command.bigDecimalValueOfParameterNamedDefaultToNullIfZero("openingBalance"));
+        this.currentBalance = this.openingBalance;
+        this.isSmsActive = command.booleanPrimitiveValueOfParameterNamed("isSmsActive");
+        this.isEmailActive = command.booleanPrimitiveValueOfParameterNamed("isEmailActive");
+        this.interestCalc = BigDecimal.ZERO;
+        this.interestDate = command.localDateValueOfParameterNamed("interestDate");
+        this.odInterestCalc = BigDecimal.ZERO;
+        this.odInterestDate = null;
+        this.spDescription = command.stringValueOfParameterNamedAllowingNull("spDescription");
+        this.freezeCode = StringUtils.defaultIfBlank(command.stringValueOfParameterNamedAllowingNull("freezeCode"), "Normal");
+        this.advCode = StringUtils.defaultIfBlank(command.stringValueOfParameterNamedAllowingNull("advCode"), "None");
+        this.creditToBranch = command.stringValueOfParameterNamedAllowingNull("creditToBranch");
+        this.creditToAccountType = command.stringValueOfParameterNamedAllowingNull("creditToAccountType");
+        this.creditToAccount = command.stringValueOfParameterNamedAllowingNull("creditToAccount");
+        this.nomineeApplicable = command.booleanPrimitiveValueOfParameterNamed("nomineeApplicable");
+        this.nomineeSplitMode = StringUtils.defaultIfBlank(command.stringValueOfParameterNamedAllowingNull("nomineeSplitMode"),
+                "Percentage");
+        this.status = STATUS_ACTIVE;
+
+        recalculateTerm();
+    }
+
+    /**
+     * Takes the scheme's interest rate. The rate belongs to the scheme, not to the counter: it is set
+     * when the account is opened or moved to another scheme, and again on every open account whenever
+     * the bank changes the scheme's rate, with the maturity figure worked out again on it.
+     */
+    public void takeSchemeRate(final BigDecimal schemeRate) {
+        this.interestRate = schemeRate == null ? BigDecimal.ZERO : schemeRate;
+        recalculateTerm();
+    }
+
+    /**
+     * Works out the maturity date and amount from the terms just set.
+     *
+     * Both are quoted to the customer when the account is opened, so neither is taken from the
+     * request: a figure the caller supplies is a figure the caller can get wrong or tamper with.
+     * The screen shows the same numbers as a preview, worked out the same way.
+     */
+    private void recalculateTerm() {
+        if (this.openingDate != null) {
+            if (this.month != null && this.month > 0) {
+                this.maturityDate = this.openingDate.plusMonths(this.month);
+                // Collection runs every day of the term without a break, so the number of instalments
+                // is the number of days - it is not a separate thing for anyone to type.
+                //
+                // It was asked for, and a figure below the term's own length quietly broke the
+                // maturity quote: an account collecting a hundred rupees a day for thirty days with
+                // ten instalments keyed against it was quoted a thousand rupees and would collect
+                // three. Working it out here means the two can no longer disagree.
+                this.days = (int) ChronoUnit.DAYS.between(this.openingDate, this.maturityDate);
+            } else if (this.days != null && this.days > 0) {
+                // No month given, so the term is the run of days itself and days stands as entered.
+                this.maturityDate = this.openingDate.plusDays(this.days);
+            }
+        }
+        this.maturityAmount = calculateMaturityAmount();
+    }
+
+    /**
+     * What the account matures to: every instalment paid in, plus simple interest on each for the
+     * time it sits until maturity.
+     *
+     * The first instalment earns over the whole term and the last over none, which comes to
+     * n(n+1)/2 instalment-days of interest across n instalments. At a zero rate this is just the
+     * instalments themselves.
+     */
+    private BigDecimal calculateMaturityAmount() {
+        if (this.dailyDepositAmount == null || this.days == null || this.days <= 0
+                || this.dailyDepositAmount.compareTo(BigDecimal.ZERO) <= 0) {
+            return BigDecimal.ZERO;
+        }
+
+        final BigDecimal instalments = BigDecimal.valueOf(this.days);
+        final BigDecimal principal = this.dailyDepositAmount.multiply(instalments);
+
+        final BigDecimal rate = this.interestRate == null ? BigDecimal.ZERO : this.interestRate;
+        if (rate.compareTo(BigDecimal.ZERO) <= 0) {
+            return principal.setScale(2, RoundingMode.HALF_UP);
+        }
+
+        final BigDecimal instalmentDays = instalments.multiply(instalments.add(BigDecimal.ONE))
+                .divide(BigDecimal.valueOf(2), MATH_CONTEXT);
+        final BigDecimal interest = this.dailyDepositAmount.multiply(instalmentDays).multiply(rate)
+                .divide(BigDecimal.valueOf(100), MATH_CONTEXT)
+                .divide(BigDecimal.valueOf(DAYS_IN_YEAR), MATH_CONTEXT);
+
+        return principal.add(interest).setScale(2, RoundingMode.HALF_UP);
+    }
+
+    public static Party fromJson(final Client client, final Agent agent, final Office office, final String partyCode,
+            final JsonCommand command) {
+        return new Party(client, agent, office, partyCode, command);
+    }
+
+    /** Moves this account to another branch, which a party update may do on its own. */
+    public void changeOffice(final Office newOffice) {
+        this.office = newOffice;
+    }
+
+    private static BigDecimal orZero(final BigDecimal value) {
+        return value == null ? BigDecimal.ZERO : value;
+    }
+
+    public void addNominee(final PartyNominee nominee) {
+        nominee.setParty(this);
+        this.nominees.add(nominee);
+    }
+
+    public void resetNominees() {
+        this.nominees.clear();
+    }
+
+    public void changeClient(final Client newClient) {
+        this.client = newClient;
+    }
+
+    public void changeAgent(final Agent newAgent) {
+        this.agent = newAgent;
+    }
+
+    /**
+     * Links this Party to an existing real Savings Account, resolved by account number in the write
+     * service. There is no unlink - once a Party's DDS scheme is tied to a real account, it stays
+     * tied.
+     */
+    public void linkSavingsAccount(final Long savingsAccountId) {
+        this.savingsAccountId = savingsAccountId;
+    }
+
+    /** Numbers the account from its id, the same way 0514 numbered the accounts already open. */
+    public void assignAccountNo() {
+        if (this.accountNo == null && getId() != null) {
+            this.accountNo = "DDS" + String.format("%09d", getId());
+        }
+    }
+
+    public BigDecimal credit(final BigDecimal amount) {
+        this.currentBalance = this.currentBalance.add(amount);
+        return this.currentBalance;
+    }
+
+    public BigDecimal debit(final BigDecimal amount) {
+        this.currentBalance = this.currentBalance.subtract(amount);
+        return this.currentBalance;
+    }
+
+    /**
+     * Turns a minor's account over to its holder, now that they have come of age and been identified.
+     *
+     * Until this the guardian operates the account and the bank deals with them. After it the customer
+     * holds it in their own right, so the guardian is kept only as a record of who stood for them
+     * before - the account is no longer theirs to operate.
+     *
+     * Not done on the birthday alone. An eighteen-year-old the bank has not yet identified is somebody
+     * it cannot pay, so the turnover waits on their own KYC being verified.
+     */
+    public void becomeAdult() {
+        this.adultMinor = ADULT;
+    }
+
+    public boolean isMinor() {
+        return MINOR.equalsIgnoreCase(this.adultMinor);
+    }
+
+    private static final String MINOR = "Minor";
+    private static final String ADULT = "Adult";
+
+    public boolean isClosed() {
+        return STATUS_CLOSED.equals(this.status);
+    }
+
+    /**
+     * Closes this Party's account as of the given date. The balance must already be zero - a Party
+     * is settled to zero (a full Withdraw Deposite/payout) before it is closed, not closed with money
+     * still owed to it.
+     */
+    public void close(final LocalDate closeDate) {
+        this.status = STATUS_CLOSED;
+        this.closeDate = closeDate;
+    }
+
+    /**
+     * Interest Calculation: parks the interest earned since {@code interestDate} in the account's
+     * accrued-interest figure - the legacy screen's "Int.Calc" - and stamps the date interest is now
+     * calculated up to. The balance is untouched, because interest is not the customer's to draw on
+     * until it is posted.
+     *
+     * The stamp is what keeps this safe to re-run: a second calculation for the same date finds no
+     * days left to accrue, so the same interest cannot be earned twice.
+     */
+    public void accrueInterest(final BigDecimal amount, final LocalDate throughDate, final boolean odInterest) {
+        if (odInterest) {
+            this.odInterestCalc = this.odInterestCalc.add(amount);
+            this.odInterestDate = throughDate;
+        } else {
+            this.interestCalc = this.interestCalc.add(amount);
+            this.interestDate = throughDate;
+        }
+    }
+
+    /** How far the given interest stream has been calculated through - where the next run starts from. */
+    public LocalDate interestCalculatedThrough(final boolean odInterest) {
+        return odInterest ? this.odInterestDate : this.interestDate;
+    }
+
+    /** What the given interest stream is holding, waiting to be posted. */
+    public BigDecimal accruedInterest(final boolean odInterest) {
+        return odInterest ? this.odInterestCalc : this.interestCalc;
+    }
+
+    /**
+     * Interest Posting: moves the given amount out of accrued interest and into the balance, and
+     * returns the new balance.
+     *
+     * The amount is the one the run previewed rather than whatever is accrued at this moment, so what
+     * gets credited is always what was seen and approved. Since it comes off the accrued figure, a
+     * second posting of the same interest finds nothing left to move.
+     */
+    public BigDecimal postInterest(final BigDecimal amount, final boolean odInterest) {
+        if (odInterest) {
+            this.odInterestCalc = this.odInterestCalc.subtract(amount);
+        } else {
+            this.interestCalc = this.interestCalc.subtract(amount);
+        }
+        this.currentBalance = this.currentBalance.add(amount);
+        return this.currentBalance;
+    }
+
+    public Long clientId() {
+        return this.client.getId();
+    }
+
+    public Long agentId() {
+        return this.agent.getId();
+    }
+
+    public Map<String, Object> update(final JsonCommand command) {
+
+        final Map<String, Object> actualChanges = new LinkedHashMap<>(40);
+
+        if (command.isChangeInLongParameterNamed("clientId", this.client.getId())) {
+            actualChanges.put("clientId", command.longValueOfParameterNamed("clientId"));
+        }
+        if (command.isChangeInLongParameterNamed("agentId", this.agent.getId())) {
+            actualChanges.put("agentId", command.longValueOfParameterNamed("agentId"));
+        }
+
+        stringChange(command, actualChanges, "subType", this.subType, v -> this.subType = v);
+        stringChange(command, actualChanges, "lastAccount", this.lastAccount, v -> this.lastAccount = v);
+
+        if (command.isChangeInBooleanParameterNamed("nominal", this.nominal)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("nominal");
+            actualChanges.put("nominal", newValue);
+            this.nominal = newValue;
+        }
+
+        stringChange(command, actualChanges, "aadharNo", this.aadharNo, v -> this.aadharNo = v);
+        stringChange(command, actualChanges, "partyName", this.partyName, v -> this.partyName = v);
+        stringChange(command, actualChanges, "partyName1", this.partyName1, v -> this.partyName1 = v);
+        stringChange(command, actualChanges, "address1", this.address1, v -> this.address1 = v);
+        stringChange(command, actualChanges, "address2", this.address2, v -> this.address2 = v);
+        stringChange(command, actualChanges, "address3", this.address3, v -> this.address3 = v);
+        stringChange(command, actualChanges, "city", this.city, v -> this.city = v);
+        stringChange(command, actualChanges, "pincode", this.pincode, v -> this.pincode = v);
+        stringChange(command, actualChanges, "gender", this.gender, v -> this.gender = v);
+        stringChange(command, actualChanges, "panCardNo", this.panCardNo, v -> this.panCardNo = v);
+        stringChange(command, actualChanges, "telephone", this.telephone, v -> this.telephone = v);
+        stringChange(command, actualChanges, "mobileNoSms", this.mobileNoSms, v -> this.mobileNoSms = v);
+        stringChange(command, actualChanges, "operation", this.operation, v -> this.operation = v);
+
+        if (command.isChangeInDateParameterNamed("birthDate", this.birthDate)) {
+            actualChanges.put("birthDate", command.stringValueOfParameterNamed("birthDate"));
+            this.birthDate = command.localDateValueOfParameterNamed("birthDate");
+        }
+
+        stringChange(command, actualChanges, "occupation", this.occupation, v -> this.occupation = v);
+        stringChange(command, actualChanges, "risk", this.risk, v -> this.risk = v);
+        stringChange(command, actualChanges, "ckycId", this.ckycId, v -> this.ckycId = v);
+        stringChange(command, actualChanges, "adultMinor", this.adultMinor, v -> this.adultMinor = v);
+
+        if (command.isChangeInDateParameterNamed("minorDate", this.minorDate)) {
+            actualChanges.put("minorDate", command.stringValueOfParameterNamed("minorDate"));
+            this.minorDate = command.localDateValueOfParameterNamed("minorDate");
+        }
+
+        if (command.isChangeInLongParameterNamed("guardianClientId", this.guardianClientId)) {
+            final Long newValue = command.longValueOfParameterNamed("guardianClientId");
+            actualChanges.put("guardianClientId", newValue);
+            this.guardianClientId = newValue;
+        }
+
+        stringChange(command, actualChanges, "minAccountOpt", this.minAccountOpt, v -> this.minAccountOpt = v);
+        stringChange(command, actualChanges, "relation", this.relation, v -> this.relation = v);
+
+        if (command.isChangeInDateParameterNamed("openingDate", this.openingDate)) {
+            actualChanges.put("openingDate", command.stringValueOfParameterNamed("openingDate"));
+            this.openingDate = command.localDateValueOfParameterNamed("openingDate");
+        }
+
+        if (command.isChangeInIntegerParameterNamed("month", this.month)) {
+            final Integer newValue = command.integerValueOfParameterNamed("month");
+            actualChanges.put("month", newValue);
+            this.month = newValue;
+        }
+
+        if (command.isChangeInDateParameterNamed("reopenDate", this.reopenDate)) {
+            actualChanges.put("reopenDate", command.stringValueOfParameterNamed("reopenDate"));
+            this.reopenDate = command.localDateValueOfParameterNamed("reopenDate");
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("depositAmount", this.depositAmount)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("depositAmount");
+            actualChanges.put("depositAmount", newValue);
+            this.depositAmount = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("dailyDepositAmount", this.dailyDepositAmount)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("dailyDepositAmount");
+            actualChanges.put("dailyDepositAmount", newValue);
+            this.dailyDepositAmount = newValue;
+        }
+
+        if (command.isChangeInIntegerParameterNamed("days", this.days)) {
+            final Integer newValue = command.integerValueOfParameterNamed("days");
+            actualChanges.put("days", newValue);
+            this.days = newValue;
+        }
+
+        // The rate is not edited here: it is the scheme's, taken when the account is opened or moved
+        // to another scheme - see takeSchemeRate.
+
+        stringChange(command, actualChanges, "ledgerNo", this.ledgerNo, v -> this.ledgerNo = v);
+        stringChange(command, actualChanges, "withdrawType", this.withdrawType, v -> this.withdrawType = v);
+
+        if (command.isChangeInBooleanParameterNamed("lien", this.lien)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("lien");
+            actualChanges.put("lien", newValue);
+            this.lien = newValue;
+        }
+
+        stringChange(command, actualChanges, "lienReason", this.lienReason, v -> this.lienReason = v);
+
+        // A released account explains nothing, so the reason goes with the hold. Leaving it behind
+        // would have the screen read "Lien: No, held for Loan #1234" - a sentence that contradicts
+        // itself, and which somebody will one day read as the account still being held.
+        //
+        // Nothing is lost: what it was held for, who released it and when are all on the command the
+        // release rode in on, which maker-checker keeps.
+        if (!this.lien && this.lienReason != null) {
+            actualChanges.put("lienReason", null);
+            this.lienReason = null;
+        }
+
+        if (command.isChangeInDateParameterNamed("payDate", this.payDate)) {
+            actualChanges.put("payDate", command.stringValueOfParameterNamed("payDate"));
+            this.payDate = command.localDateValueOfParameterNamed("payDate");
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("paymentAmount", this.paymentAmount)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("paymentAmount");
+            actualChanges.put("paymentAmount", newValue);
+            this.paymentAmount = newValue;
+        }
+
+        if (command.isChangeInBigDecimalParameterNamed("openingBalance", this.openingBalance)) {
+            final BigDecimal newValue = command.bigDecimalValueOfParameterNamed("openingBalance");
+            actualChanges.put("openingBalance", newValue);
+            this.openingBalance = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("isSmsActive", this.isSmsActive)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("isSmsActive");
+            actualChanges.put("isSmsActive", newValue);
+            this.isSmsActive = newValue;
+        }
+
+        if (command.isChangeInBooleanParameterNamed("isEmailActive", this.isEmailActive)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("isEmailActive");
+            actualChanges.put("isEmailActive", newValue);
+            this.isEmailActive = newValue;
+        }
+
+        if (command.isChangeInDateParameterNamed("interestDate", this.interestDate)) {
+            actualChanges.put("interestDate", command.stringValueOfParameterNamed("interestDate"));
+            this.interestDate = command.localDateValueOfParameterNamed("interestDate");
+        }
+
+        stringChange(command, actualChanges, "spDescription", this.spDescription, v -> this.spDescription = v);
+        stringChange(command, actualChanges, "freezeCode", this.freezeCode, v -> this.freezeCode = v);
+        stringChange(command, actualChanges, "advCode", this.advCode, v -> this.advCode = v);
+        stringChange(command, actualChanges, "creditToBranch", this.creditToBranch, v -> this.creditToBranch = v);
+        stringChange(command, actualChanges, "creditToAccountType", this.creditToAccountType, v -> this.creditToAccountType = v);
+        stringChange(command, actualChanges, "creditToAccount", this.creditToAccount, v -> this.creditToAccount = v);
+
+        if (command.isChangeInBooleanParameterNamed("nomineeApplicable", this.nomineeApplicable)) {
+            final boolean newValue = command.booleanPrimitiveValueOfParameterNamed("nomineeApplicable");
+            actualChanges.put("nomineeApplicable", newValue);
+            this.nomineeApplicable = newValue;
+        }
+
+        stringChange(command, actualChanges, "nomineeSplitMode", this.nomineeSplitMode, v -> this.nomineeSplitMode = v);
+
+        // Correcting a term, an instalment or the rate has to move the maturity figures with it -
+        // otherwise the account keeps quoting what it was worth under the old terms.
+        final LocalDate maturityDateBefore = this.maturityDate;
+        final BigDecimal maturityAmountBefore = this.maturityAmount;
+        recalculateTerm();
+        if (!java.util.Objects.equals(maturityDateBefore, this.maturityDate)) {
+            actualChanges.put("maturityDate", this.maturityDate);
+        }
+        if (maturityAmountBefore == null || this.maturityAmount.compareTo(maturityAmountBefore) != 0) {
+            actualChanges.put("maturityAmount", this.maturityAmount);
+        }
+
+        return actualChanges;
+    }
+
+    private void stringChange(final JsonCommand command, final Map<String, Object> actualChanges, final String paramName,
+            final String existingValue, final Consumer<String> setter) {
+        if (command.isChangeInStringParameterNamed(paramName, existingValue)) {
+            final String newValue = command.stringValueOfParameterNamed(paramName);
+            actualChanges.put(paramName, newValue);
+            setter.accept(newValue);
+        }
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/domain/PartyNominee.java

@@ -0,0 +1,146 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+
+/**
+ * A single nominee recorded against a {@link Party}. Maker-checker on nominee edits is enforced at
+ * the command layer (the whole Party update goes through the standard maker-checker command flow),
+ * not on this child row individually.
+ *
+ * Audited in its own right rather than only through the party: this row decides who receives a
+ * customer's money after them, and "the party changed at 16:19" does not say that the person named
+ * to receive it was replaced, nor by whom.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_party_nominee")
+public class PartyNominee extends AbstractAuditableCustom {
+
+    @ManyToOne
+    @JoinColumn(name = "party_id", nullable = false)
+    private Party party;
+
+    @Column(name = "nomination_date", nullable = false)
+    private LocalDate nominationDate;
+
+    @Column(name = "name", length = 100, nullable = false)
+    private String name;
+
+    @Column(name = "mobile_no", length = 20)
+    private String mobileNo;
+
+    @Column(name = "birth_date")
+    private LocalDate birthDate;
+
+    /**
+     * Whether this nominee was under age when nominated, worked out from their date of birth rather
+     * than asked for.
+     *
+     * Asked for, it was got wrong: a ten-year-old was recorded as not a minor, and so no guardian
+     * was required for them. The date of birth is captured either way and already holds the answer,
+     * so the clerk is not asked a second time in a form that can disagree with the first.
+     *
+     * Kept as a stored column rather than worked out on reading, because it is the age at the
+     * moment of nomination that the record is of - a nominee who has since come of age was still a
+     * minor on the day they were named, and the guardian named beside them belongs to that day.
+     */
+    @Column(name = "minor", nullable = false)
+    private boolean minor;
+
+    /** India's age of majority, which is what makes a nominee one who needs a guardian named. */
+    private static final int AGE_OF_MAJORITY = 18;
+
+    @Column(name = "relation", length = 40, nullable = false)
+    private String relation;
+
+    @Column(name = "gender", length = 20, nullable = false)
+    private String gender;
+
+    @Column(name = "guardian_name", length = 100)
+    private String guardianName;
+
+    /**
+     * What this nominee is entitled to, under a Percentage split. Null under a Sequence split, where
+     * the order the nominees are held in is the entitlement and there is no share to state.
+     */
+    @Column(name = "share_percent", precision = 5, scale = 2)
+    private BigDecimal sharePercent;
+
+    /**
+     * Where this nominee stands in the order the bank pays, under a Sequence split. Null under a
+     * Percentage split, where everyone is paid at once and there is no first.
+     */
+    @Column(name = "sequence_no")
+    private Integer sequenceNo;
+
+    protected PartyNominee() {
+        //
+    }
+
+    public PartyNominee(final LocalDate nominationDate, final String name, final String mobileNo, final LocalDate birthDate,
+            final String relation, final String gender, final String guardianName, final BigDecimal sharePercent,
+            final Integer sequenceNo) {
+        this.nominationDate = nominationDate;
+        // Trimmed on the way in. A relation typed as "friend " is a different value from "friend"
+        // to everything that groups or matches on it, and the trailing space is invisible on screen
+        // - so the two read as the same relation everywhere except where it counts.
+        this.name = StringUtils.trimToNull(name);
+        this.mobileNo = StringUtils.trimToNull(mobileNo);
+        this.birthDate = birthDate;
+        this.minor = isUnderAgeOn(birthDate, nominationDate);
+        this.relation = StringUtils.trimToNull(relation);
+        this.gender = StringUtils.trimToNull(gender);
+        this.guardianName = StringUtils.trimToNull(guardianName);
+        this.sharePercent = sharePercent;
+        this.sequenceNo = sequenceNo;
+    }
+
+    void setParty(final Party party) {
+        this.party = party;
+    }
+
+    /**
+     * Whether someone born on the given day was still under age on the day they were nominated.
+     *
+     * Measured against the nomination date rather than today, so a nomination reads the same in ten
+     * years as it did when it was made - and a nominee who has since come of age does not quietly
+     * lose the guardian who was named for them at the time.
+     *
+     * A missing date of birth is treated as not a minor: the field is required, so a null here can
+     * only be a record made before it was, and guessing "minor" would demand a guardian for someone
+     * who may well be eighty.
+     */
+    public static boolean isUnderAgeOn(final LocalDate birthDate, final LocalDate nominationDate) {
+        if (birthDate == null || nominationDate == null) {
+            return false;
+        }
+        return birthDate.isAfter(nominationDate.minusYears(AGE_OF_MAJORITY));
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartyAlreadyClosedException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a Close Party command, or a Party Tran collection, targets a Party that is already
+ * closed.
+ */
+public class PartyAlreadyClosedException extends AbstractPlatformDomainRuleException {
+
+    public PartyAlreadyClosedException(final String partyCode) {
+        super("error.msg.party.already.closed", "Party " + partyCode + " is already closed", partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartyHasBalanceException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a Close Party command is attempted while the Party's balance is still non-zero - the
+ * remaining balance must be paid out (a Withdraw Deposite to zero) before the account can be closed.
+ */
+public class PartyHasBalanceException extends AbstractPlatformDomainRuleException {
+
+    public PartyHasBalanceException(final String partyCode) {
+        super("error.msg.party.has.balance", "Party " + partyCode + " still has a non-zero balance and cannot be closed", partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartyNotFoundException.java

@@ -0,0 +1,40 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+import org.springframework.dao.EmptyResultDataAccessException;
+
+/**
+ * A {@link RuntimeException} thrown when a DDS party resource is not found.
+ */
+public class PartyNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public PartyNotFoundException(final Long id) {
+        super("error.msg.party.id.invalid", "Party with identifier " + id + " does not exist", id);
+    }
+
+    public PartyNotFoundException(final Long id, final EmptyResultDataAccessException e) {
+        super("error.msg.party.id.invalid", "Party with identifier " + id + " does not exist", id, e);
+    }
+
+    public PartyNotFoundException(final String partyCode) {
+        super("error.msg.party.code.invalid", "Party with code " + partyCode + " does not exist", partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartySavingsAccountClientMismatchException.java

@@ -0,0 +1,33 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when the savingsAccountNo given for a Party belongs to a different client than the Party's
+ * own clientId - a Party can only be linked to its own client's savings account.
+ */
+public class PartySavingsAccountClientMismatchException extends AbstractPlatformDomainRuleException {
+
+    public PartySavingsAccountClientMismatchException(final String savingsAccountNo) {
+        super("error.msg.party.savings.account.client.mismatch",
+                "Savings account " + savingsAccountNo + " does not belong to this party's client", savingsAccountNo);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartySavingsAccountNotFoundException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+
+/**
+ * Thrown when a Party's savingsAccountNo does not match any non-closed Savings Account.
+ */
+public class PartySavingsAccountNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public PartySavingsAccountNotFoundException(final String savingsAccountNo) {
+        super("error.msg.party.savings.account.not.found", "No open savings account found with account number " + savingsAccountNo,
+                savingsAccountNo);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/party/exception/PartySubTypeNotActiveException.java

@@ -0,0 +1,38 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a Party's subType is not the code of an active DDS Account Type.
+ *
+ * The Party screen's Sub Type is chosen from the DDS Account Type master, so an unknown code means
+ * the caller invented one, and a deactivated code means the scheme has been retired - existing
+ * parties on it keep running, but no new party may be opened under it.
+ */
+public class PartySubTypeNotActiveException extends AbstractPlatformDomainRuleException {
+
+    public PartySubTypeNotActiveException(final String subType, final boolean exists) {
+        super(exists ? "error.msg.party.sub.type.not.active" : "error.msg.party.sub.type.invalid",
+                exists ? "Account type " + subType + " has been deactivated, so no new party can be opened under it"
+                        : "There is no DDS account type with the code " + subType,
+                subType);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/report/data/DdsReportData.java

@@ -0,0 +1,45 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.report.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+import lombok.Builder;
+import lombok.Getter;
+
+/**
+ * A generic tabular result shape shared by every DDS report - one column list plus one row list, both
+ * keyed the same way, so a single report viewer screen can render any of them without a bespoke
+ * result type per report.
+ */
+@Getter
+@Builder
+public final class DdsReportData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final String reportKey;
+    private final boolean available;
+    private final String message;
+    private final List<String> columns;
+    private final List<Map<String, Object>> rows;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/data/PartyTransactionData.java

@@ -0,0 +1,54 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Builder;
+import lombok.Getter;
+
+@Getter
+@Builder
+public final class PartyTransactionData implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private final Long id;
+    private final Long partyId;
+    private final String partyCode;
+    private final String partyName;
+    private final Long agentId;
+    private final String agentCode;
+    private final LocalDate transactionDate;
+    private final String transactionType;
+    private final String direction;
+    private final String transactionMode;
+    private final String accountType;
+    private final String accountNo;
+    private final BigDecimal amount;
+    private final String chequeNo;
+    private final String tokenNo;
+    private final String description;
+    private final BigDecimal balanceAfterTransaction;
+    /** The DDS voucher this line moved under, e.g. DDS/29092026/0001; empty on lines from before vouchers. */
+    private final String voucherNo;
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/domain/DdsTransactionMode.java

@@ -0,0 +1,106 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.domain;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
+
+/**
+ * How money changed hands on a DDS entry: over the counter, by book transfer, or through clearing.
+ *
+ * It exists because the mode used to be a free-text field. The screen only ever offered these three,
+ * but nothing behind the screen said so, and the column filled up with two spellings of the same
+ * word - `Cash` from one path and `CASH` from another. A cash book that groups by mode then reports
+ * the same day's takings twice under two headings, which is the kind of discrepancy someone spends
+ * an afternoon chasing before finding it was never a discrepancy at all.
+ *
+ * So the list lives here, once, and both the validator and the write service read it from here. What
+ * a caller sends is matched without regard to case or surrounding space, because an integration
+ * sending `cash` is unambiguous and rejecting it would be pedantry; but what gets stored is always
+ * the label below, so the column only ever holds one spelling of each.
+ *
+ * Only entries a person makes carry a mode. Interest, commission and maturity postings are the
+ * system's own work - no cash, no cheque, nothing to record - and a transfer between two DDS accounts
+ * moves nothing across the counter either, so those are left null rather than labelled.
+ */
+public enum DdsTransactionMode {
+
+    CASH("Cash"), //
+    TRANSFER("Transfer"), //
+    CLEARING("Clearing");
+
+    private final String label;
+
+    DdsTransactionMode(final String label) {
+        this.label = label;
+    }
+
+    /** The one spelling that is ever stored or shown for this mode. */
+    public String getLabel() {
+        return this.label;
+    }
+
+    /**
+     * The mode a caller's text names, or null if it names none of them. Case and surrounding space
+     * are ignored; anything else is a mode this scheme does not have.
+     */
+    public static DdsTransactionMode fromLabel(final String value) {
+        if (value == null) {
+            return null;
+        }
+        final String trimmed = value.trim();
+        return Arrays.stream(values()).filter(mode -> mode.label.equalsIgnoreCase(trimmed)).findFirst().orElse(null);
+    }
+
+    /**
+     * The stored form of what a caller sent: the canonical label when it names a mode, and the value
+     * untouched when it does not.
+     *
+     * Unknown text is passed through rather than blanked because this is called after validation has
+     * already refused it - a silent blanking here would only hide a bug in the order of the two.
+     */
+    public static String canonicalOrOriginal(final String value) {
+        final DdsTransactionMode mode = fromLabel(value);
+        return mode == null ? value : mode.label;
+    }
+
+    /** The labels, in the order the entry screen lists them - for error messages and for callers. */
+    public static List<String> labels() {
+        return Arrays.stream(values()).map(DdsTransactionMode::getLabel).toList();
+    }
+
+    /** The labels as a reader sees them in a sentence: "Cash, Transfer, Clearing". */
+    public static String labelsForMessage() {
+        return String.join(", ", labels());
+    }
+
+    /**
+     * The same rule as {@link #fromLabel}, expressed as a regular expression, for the validator to
+     * apply - it reports a failed pattern with the parameter and message already filled in, which a
+     * hand-rolled check cannot do as tidily.
+     *
+     * Built from the labels rather than written out, so the two ways of asking the same question
+     * cannot answer it differently: add a mode above and both move together.
+     */
+    public static String acceptedPattern() {
+        return Arrays.stream(values()).map(mode -> Pattern.quote(mode.label)).collect(Collectors.joining("|", "(?i)\\s*(", ")\\s*"));
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/domain/PartyTransaction.java

@@ -0,0 +1,122 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.ManyToOne;
+import jakarta.persistence.PostPersist;
+import jakarta.persistence.Table;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+import org.apache.fineract.infrastructure.core.domain.AbstractAuditableCustom;
+import org.apache.fineract.organisation.agent.domain.Agent;
+import org.apache.fineract.portfolio.dds.party.domain.Party;
+import org.apache.fineract.portfolio.dds.voucher.DdsVoucherScope;
+
+/**
+ * A single posted entry on the DDS ledger: a Party's day's collection ("Party Tran", direction
+ * CREDIT), one leg of a "Withdraw Deposite" transfer between two parties (the creditor leg CREDIT,
+ * the debtor leg DEBIT), or an Agent's settlement of collected cash to its branch ("Agent Tran",
+ * direction DEBIT - no {@link Party} involved, so {@code party} is null for this type).
+ * {@code balanceAfterTransaction} holds the Party's balance for Party-linked rows, or the Agent's
+ * balance for an Agent Tran row. Immutable once posted - like any transaction, it is reversed with
+ * an opposing entry, not edited, so there is deliberately no update API for this entity.
+ */
+@Getter
+@Entity
+@Table(name = "m_dds_party_transaction")
+public class PartyTransaction extends AbstractAuditableCustom {
+
+    @ManyToOne
+    @JoinColumn(name = "party_id")
+    private Party party;
+
+    @ManyToOne
+    @JoinColumn(name = "agent_id", nullable = false)
+    private Agent agent;
+
+    @Column(name = "transaction_date", nullable = false)
+    private LocalDate transactionDate;
+
+    @Column(name = "transaction_type", length = 30, nullable = false)
+    private String transactionType;
+
+    @Column(name = "direction", length = 10, nullable = false)
+    private String direction;
+
+    @Column(name = "transaction_mode", length = 20)
+    private String transactionMode;
+
+    @Column(name = "account_type", length = 100)
+    private String accountType;
+
+    @Column(name = "account_no", length = 50)
+    private String accountNo;
+
+    @Column(name = "amount", scale = 6, precision = 19, nullable = false)
+    private BigDecimal amount;
+
+    @Column(name = "cheque_no", length = 40)
+    private String chequeNo;
+
+    @Column(name = "token_no", length = 40)
+    private String tokenNo;
+
+    @Column(name = "description", length = 500)
+    private String description;
+
+    @Column(name = "balance_after_transaction", scale = 6, precision = 19, nullable = false)
+    private BigDecimal balanceAfterTransaction;
+
+    protected PartyTransaction() {
+        //
+    }
+
+    public PartyTransaction(final Party party, final Agent agent, final LocalDate transactionDate, final String transactionType,
+            final String direction, final String transactionMode, final String accountType, final String accountNo,
+            final BigDecimal amount, final String chequeNo, final String tokenNo, final String description,
+            final BigDecimal balanceAfterTransaction) {
+        this.party = party;
+        this.agent = agent;
+        this.transactionDate = transactionDate;
+        this.transactionType = transactionType;
+        this.direction = direction;
+        this.transactionMode = transactionMode;
+        this.accountType = accountType;
+        this.accountNo = accountNo;
+        this.amount = amount;
+        this.chequeNo = chequeNo;
+        this.tokenNo = tokenNo;
+        this.description = description;
+        this.balanceAfterTransaction = balanceAfterTransaction;
+    }
+
+    /**
+     * Notes this line against the operation that wrote it, so the operation's voucher number can be
+     * stamped on it. The voucher number itself is not mapped here: it is written once, by SQL, after
+     * the voucher is raised, and a mapped field would be written back as null by any later save.
+     */
+    @PostPersist
+    private void recordInVoucherScope() {
+        DdsVoucherScope.recordPartyTransaction(getId());
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/exception/InsufficientAgentBalanceException.java

@@ -0,0 +1,33 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when an Agent Tran settlement amount exceeds the Agent's current (collected but not yet
+ * settled) balance.
+ */
+public class InsufficientAgentBalanceException extends AbstractPlatformDomainRuleException {
+
+    public InsufficientAgentBalanceException(final String agentCode) {
+        super("error.msg.agent.insufficient.balance",
+                "Agent " + agentCode + " does not have sufficient collected balance for this settlement", agentCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/exception/InsufficientPartyBalanceException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a Withdraw Deposite transfer would take the debtor Party's balance below zero.
+ */
+public class InsufficientPartyBalanceException extends AbstractPlatformDomainRuleException {
+
+    public InsufficientPartyBalanceException(final String partyCode) {
+        super("error.msg.party.insufficient.balance", "Party " + partyCode + " does not have sufficient balance for this transfer",
+                partyCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/exception/PartyNotCollectedByAgentException.java

@@ -0,0 +1,38 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformDomainRuleException;
+
+/**
+ * Thrown when a transaction is posted against an agent who does not collect for the party named on
+ * it.
+ *
+ * The balances would still come out right, but the transaction would be filed under the wrong
+ * agent - and every agent-wise report is built from exactly that. An agent would show collections
+ * and transfers for customers who are not theirs, and the officer reading the report has no way to
+ * tell.
+ */
+public class PartyNotCollectedByAgentException extends AbstractPlatformDomainRuleException {
+
+    public PartyNotCollectedByAgentException(final String partyCode, final String agentCode) {
+        super("error.msg.party.not.collected.by.agent", "Party " + partyCode + " is not collected by agent " + agentCode,
+                partyCode, agentCode);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/transaction/exception/PartyTransactionNotFoundException.java

@@ -0,0 +1,32 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.transaction.exception;
+
+import org.apache.fineract.infrastructure.core.exception.AbstractPlatformResourceNotFoundException;
+import org.springframework.dao.EmptyResultDataAccessException;
+
+/**
+ * A {@link RuntimeException} thrown when a DDS party transaction resource is not found.
+ */
+public class PartyTransactionNotFoundException extends AbstractPlatformResourceNotFoundException {
+
+    public PartyTransactionNotFoundException(final Long id, final EmptyResultDataAccessException e) {
+        super("error.msg.partytransaction.id.invalid", "Party transaction with identifier " + id + " does not exist", id, e);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/dds/voucher/DdsVoucherScope.java

@@ -0,0 +1,105 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.voucher;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * What one DDS operation moved, gathered while it runs so a single voucher can be raised for it at
+ * the end.
+ *
+ * A payout, an early closure, a posting run or a transfer each writes several ledger legs and
+ * passbook lines from several places - the interest brought up to date, the recovery, the payout
+ * itself. The voucher is the slip for the whole operation, not for each leg, so the legs are noted
+ * here as they are written and turned into one voucher when the operation finishes.
+ *
+ * Held per thread, since an operation runs on one thread from start to finish - including a posting
+ * run handed to a background thread, which opens its own scope there. Outside a scope nothing is
+ * recorded.
+ */
+public final class DdsVoucherScope {
+
+    /** A voucher side with no ledger leg behind it - a move between two accounts on the same GL. */
+    public record Line(String entryType, Long glAccountId, String partyName, String accountNo, BigDecimal amount, String description) {}
+
+    private static final ThreadLocal<DdsVoucherScope> CURRENT = new ThreadLocal<>();
+
+    private final Set<String> ledgerTransactionIds = new LinkedHashSet<>();
+    private final List<Long> partyTransactionIds = new ArrayList<>();
+    private final List<Line> extraLines = new ArrayList<>();
+
+    private DdsVoucherScope() {}
+
+    /** The scope now open on this thread, or null. */
+    public static DdsVoucherScope current() {
+        return CURRENT.get();
+    }
+
+    /** Opens a scope on this thread. The caller must {@link #close} it. */
+    public static DdsVoucherScope open() {
+        final DdsVoucherScope scope = new DdsVoucherScope();
+        CURRENT.set(scope);
+        return scope;
+    }
+
+    public static void close() {
+        CURRENT.remove();
+    }
+
+    /** Notes a ledger transaction written for the operation in progress. */
+    public static void recordLedgerTransaction(final String transactionId) {
+        final DdsVoucherScope scope = CURRENT.get();
+        if (scope != null && transactionId != null) {
+            scope.ledgerTransactionIds.add(transactionId);
+        }
+    }
+
+    /** Notes a passbook line written for the operation in progress, so it can carry the voucher number. */
+    public static void recordPartyTransaction(final Long partyTransactionId) {
+        final DdsVoucherScope scope = CURRENT.get();
+        if (scope != null && partyTransactionId != null) {
+            scope.partyTransactionIds.add(partyTransactionId);
+        }
+    }
+
+    /** Adds a voucher side the ledger does not show - see {@link Line}. */
+    public static void addLine(final Line line) {
+        final DdsVoucherScope scope = CURRENT.get();
+        if (scope != null && line != null) {
+            scope.extraLines.add(line);
+        }
+    }
+
+    public Set<String> getLedgerTransactionIds() {
+        return Collections.unmodifiableSet(this.ledgerTransactionIds);
+    }
+
+    public List<Long> getPartyTransactionIds() {
+        return Collections.unmodifiableList(this.partyTransactionIds);
+    }
+
+    public List<Line> getExtraLines() {
+        return Collections.unmodifiableList(this.extraLines);
+    }
+}

fineract-core/src/main/java/org/apache/fineract/portfolio/savings/SavingsApiConstants.java

@@ -278,6 +278,7 @@ public class SavingsApiConstants {
     // Additional custom fields
     public static final String balanceFrequencyParamName = "balanceFrequency";
     public static final String accountClosedZeroBalanceInDayClosingParamName = "accountClosedZeroBalanceInDayClosing";
+    public static final String productCategoryParamName = "productCategory";
 
     // Current Product — new UI fields
     public static final String balanceSwapOptionParamName = "balanceSwapOption";

fineract-core/src/main/java/org/apache/fineract/portfolio/savings/data/SavingsProductData.java

@@ -144,6 +144,7 @@ public final class SavingsProductData implements Serializable {
     @Getter @Setter private Boolean enableLockinPeriod;
     @Getter @Setter private String balanceFrequency;
     @Getter @Setter private Boolean accountClosedZeroBalanceInDayClosing;
+    @Getter @Setter private String productCategory;
 
     // New current product fields
     @Getter @Setter private Boolean balanceSwapOption;

fineract-core/src/main/java/org/apache/fineract/portfolio/savings/domain/interest/PostingPeriod.java

@@ -256,7 +256,16 @@ public final class PostingPeriod {
         this.daysInYear = daysInYear;
         this.compoundingPeriods = compoundingPeriods;
 
-        if (isSavingsInterestPostingAtCurrentPeriodEnd) {
+        if (isUserPosting) {
+            // "Post interest as on D" — a closure, or the same action from the account screen. The
+            // period it covers ends at D-1, because interest is earned up to but not including the
+            // day it is paid, and SavingsHelper closes the period there. The transaction itself
+            // still belongs on D: that is the day the member was credited, the day the branch did
+            // the work, and the day the cash is handed over. Dating it to the period end instead
+            // stamps it a day before the account was even closed, and the ledger then disagrees with
+            // the closure request, the voucher and the passbook — all of which carry D.
+            this.dateOfPostingTransaction = periodInterval.endDate().plusDays(1);
+        } else if (isSavingsInterestPostingAtCurrentPeriodEnd) {
             this.dateOfPostingTransaction = periodInterval.endDate();
         } else {
             this.dateOfPostingTransaction = periodInterval.endDate().plusDays(1);

fineract-core/src/test/java/org/apache/fineract/organisation/agent/domain/AgentTest.java

@@ -0,0 +1,252 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.organisation.agent.domain;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import org.apache.fineract.organisation.office.domain.Office;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.dds.DdsCommands;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+/**
+ * What a collection agent is holding and what they are owed.
+ *
+ * Two separate pots, and keeping them separate is the point: the cash balance is the bank's money
+ * sitting in the agent's bag, and the commission is the agent's own earnings. Mixing them up would
+ * either lose the bank's cash or pay an agent twice, so each of these checks one and leaves the
+ * other alone.
+ */
+class AgentTest {
+
+    private Agent agent(final String extraJson) {
+        final Client client = Mockito.mock(Client.class);
+        final String json = """
+                {
+                  "clientId": 1, "agentNameId": "Test Agent", "agentAddress1": "Somewhere",
+                  "agentCity": "Bhopal", "agentPinCode": "462016",
+                  "agentSavingAccountType": "SD Product", "agentSavingAccountNo": "002002000100011",
+                  "agentOpeningDate": "01 September 2026", "agentBirthDate": "01 January 1990",
+                  "dateFormat": "dd MMMM yyyy", "locale": "en"
+                  %s
+                }
+                """.formatted(extraJson);
+        return Agent.fromJson(client, "AG0001", office("Head Office"), DdsCommands.of(json));
+    }
+
+    private Office office(final String name) {
+        final Office office = Mockito.mock(Office.class);
+        Mockito.lenient().when(office.getName()).thenReturn(name);
+        return office;
+    }
+
+    @Nested
+    @DisplayName("Cash the agent is carrying")
+    class Cash {
+
+        @Test
+        void aCollectionRaisesTheCashTheAgentHolds() {
+            final Agent agent = agent("");
+
+            assertEquals(new BigDecimal("100"), agent.credit(new BigDecimal("100")));
+            assertEquals(new BigDecimal("400"), agent.credit(new BigDecimal("300")));
+        }
+
+        @Test
+        void settlingAtABranchLowersIt() {
+            final Agent agent = agent("");
+            agent.credit(new BigDecimal("500"));
+
+            assertEquals(new BigDecimal("200"), agent.settle(new BigDecimal("300")));
+        }
+
+        /** What the Close Account guard reads: money still out with an agent stops them being closed. */
+        @Test
+        void anAgentHoldsCashUntilEverythingIsSettled() {
+            final Agent agent = agent("");
+            assertFalse(agent.holdsCash());
+
+            agent.credit(new BigDecimal("500"));
+            assertTrue(agent.holdsCash());
+
+            agent.settle(new BigDecimal("500"));
+            assertFalse(agent.holdsCash());
+        }
+
+        @Test
+        void anOpeningBalanceIsCashTheAgentAlreadyHad() {
+            final Agent agent = agent(", \"agentOpeningBalance\": 750");
+
+            assertEquals(new BigDecimal("750"), agent.getAgentCurrentBalance());
+            assertEquals(new BigDecimal("750"), agent.getAgentOpeningBalance());
+        }
+    }
+
+    @Nested
+    @DisplayName("Commission the agent has earned")
+    class Commission {
+
+        private static final LocalDate THROUGH = LocalDate.of(2026, 9, 30);
+
+        /**
+         * Accruing records what is owed and the TDS withheld from it, and stamps how far commission
+         * has been worked out - the stamp being what stops the same period being paid twice.
+         */
+        @Test
+        void accruingRecordsWhatIsOwedAndTheTaxWithheld() {
+            final Agent agent = agent("");
+
+            agent.accrueCommission(new BigDecimal("13.50"), new BigDecimal("1.50"), THROUGH);
+
+            assertEquals(new BigDecimal("13.50"), agent.getCommission());
+            assertEquals(new BigDecimal("1.50"), agent.getTdsAmount());
+            assertEquals(THROUGH, agent.getLastCommissionDate());
+        }
+
+        @Test
+        void payingItOutLeavesNothingOwed() {
+            final Agent agent = agent("");
+            agent.accrueCommission(new BigDecimal("15.00"), BigDecimal.ZERO, THROUGH);
+
+            assertEquals(new BigDecimal("0.00"), agent.payOutCommission(new BigDecimal("15.00")));
+            assertFalse(agent.isOwedCommission());
+        }
+
+        /** The guard against paying twice: a second payout comes off a figure already at zero. */
+        @Test
+        void aSecondPayoutOfTheSameCommissionFindsNothingLeft() {
+            final Agent agent = agent("");
+            agent.accrueCommission(new BigDecimal("15.00"), BigDecimal.ZERO, THROUGH);
+            agent.payOutCommission(new BigDecimal("15.00"));
+
+            assertEquals(new BigDecimal("0.00"), agent.getCommission());
+        }
+
+        /** Commission is the agent's own earnings, so paying it must not touch the bank's cash. */
+        @Test
+        void payingCommissionDoesNotTouchTheCashTheAgentIsCarrying() {
+            final Agent agent = agent("");
+            agent.credit(new BigDecimal("10000"));
+            agent.accrueCommission(new BigDecimal("15.00"), BigDecimal.ZERO, THROUGH);
+
+            agent.payOutCommission(new BigDecimal("15.00"));
+
+            assertEquals(new BigDecimal("10000"), agent.getAgentCurrentBalance());
+        }
+
+        @Test
+        void anAgentIsOwedCommissionUntilItIsPaid() {
+            final Agent agent = agent("");
+            assertFalse(agent.isOwedCommission());
+
+            agent.accrueCommission(new BigDecimal("15.00"), BigDecimal.ZERO, THROUGH);
+            assertTrue(agent.isOwedCommission());
+        }
+
+        /**
+         * The four standing amounts the Agent Commission Statement subtracts from gross commission.
+         *
+         * Set by editing an agent, not by creating one - they are figures the bank agrees with an
+         * agent after the fact, so a create request carrying them is ignored rather than trusted.
+         */
+        @Test
+        void deductionsAreTheSumOfTheFourStandingAmounts() {
+            final Agent agent = agent("");
+
+            agent.update(DdsCommands.of("""
+                    {"deductCommission": 1, "agentDeposit": 2, "festivalAdvance": 3, "otherDeduction": 4,
+                     "dateFormat": "dd MMMM yyyy", "locale": "en"}
+                    """));
+
+            assertEquals(new BigDecimal("10"), agent.totalDeductions());
+        }
+
+        /** A create request cannot set them, whatever it sends - they are agreed later, not at opening. */
+        @Test
+        void deductionsAreNotTakenFromACreateRequest() {
+            final Agent agent = agent(", \"deductCommission\": 1, \"agentDeposit\": 2,"
+                    + " \"festivalAdvance\": 3, \"otherDeduction\": 4");
+
+            assertEquals(0, agent.totalDeductions().compareTo(BigDecimal.ZERO));
+        }
+
+        @Test
+        void anAgentWithNoDeductionsSubtractsNothing() {
+            final Agent agent = agent("");
+
+            assertEquals(0, agent.totalDeductions().compareTo(BigDecimal.ZERO));
+        }
+    }
+
+    @Nested
+    @DisplayName("Which branch the agent belongs to")
+    class Branch {
+
+        /**
+         * The branch name is written from the office rather than set on its own, so the two cannot
+         * disagree - a renamed branch reads correctly without the agent being touched.
+         */
+        @Test
+        void theBranchNameComesFromTheOffice() {
+            final Agent agent = agent("");
+
+            assertEquals("Head Office", agent.getHomeBranch());
+
+            agent.setOffice(office("Borivali"));
+
+            assertEquals("Borivali", agent.getHomeBranch());
+        }
+
+        @Test
+        void anAgentWithNoOfficeHasNoBranchName() {
+            final Agent agent = agent("");
+
+            agent.setOffice(null);
+
+            assertNull(agent.getHomeBranch());
+            assertNull(agent.officeId());
+        }
+    }
+
+    @Nested
+    @DisplayName("Closing")
+    class Closing {
+
+        @Test
+        void closingAlsoStopsTheAgentCollecting() {
+            final Agent agent = agent("");
+            assertFalse(agent.isClosed());
+            assertTrue(agent.isActive());
+
+            agent.close(LocalDate.of(2026, 12, 1));
+
+            assertTrue(agent.isClosed());
+            assertFalse(agent.isActive());
+            assertEquals(LocalDate.of(2026, 12, 1), agent.getCloseDate());
+        }
+    }
+}

fineract-core/src/test/java/org/apache/fineract/portfolio/dds/DdsCommands.java

@@ -0,0 +1,47 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds;
+
+import com.google.gson.JsonElement;
+import org.apache.fineract.infrastructure.core.api.JsonCommand;
+import org.apache.fineract.infrastructure.core.serialization.FromJsonHelper;
+
+/**
+ * Builds the {@link JsonCommand} a DDS entity is created from, so a test can make a real Party or
+ * Agent the same way the API does rather than reaching into their fields.
+ *
+ * The alternative - setting fields by reflection - would test a state the application can never
+ * actually produce, which is the opposite of useful.
+ */
+public final class DdsCommands {
+
+    private static final FromJsonHelper JSON_HELPER = new FromJsonHelper();
+
+    private DdsCommands() {}
+
+    /**
+     * A command carrying the given JSON. Dates are read with the {@code dateFormat} and {@code locale}
+     * the caller puts in that JSON, exactly as a request does.
+     */
+    public static JsonCommand of(final String json) {
+        final JsonElement parsed = JSON_HELPER.parse(json);
+        return JsonCommand.from(json, parsed, JSON_HELPER, null, null, null, null, null, null, null, null, null, null, null, null, null,
+                null);
+    }
+}

fineract-core/src/test/java/org/apache/fineract/portfolio/dds/calculation/DdsCommissionCalculationTest.java

@@ -0,0 +1,141 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.calculation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.math.BigDecimal;
+import org.junit.jupiter.api.Test;
+
+/**
+ * What an agent is paid on a period's collections.
+ *
+ * The first two figures here are the ones the live system actually produced - ₹500 collected at 3%
+ * paid ₹15, and ₹1,500 paid ₹45 - so if the formula ever moves, these fail rather than the change
+ * going out unnoticed.
+ */
+class DdsCommissionCalculationTest {
+
+    private static final BigDecimal THREE_PERCENT = new BigDecimal("3");
+    private static final BigDecimal NONE = BigDecimal.ZERO;
+
+    @Test
+    void threePercentOfFiveHundredIsFifteen() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("500"), THREE_PERCENT, false, null, NONE);
+
+        assertEquals(new BigDecimal("15.00"), commission.gross());
+        assertEquals(new BigDecimal("15.00"), commission.net());
+        assertTrue(commission.isPayable());
+    }
+
+    @Test
+    void threePercentOfFifteenHundredIsFortyFive() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("1500"), THREE_PERCENT, false, null, NONE);
+
+        assertEquals(new BigDecimal("45.00"), commission.net());
+    }
+
+    /** Tax comes off the gross, not off the collections. */
+    @Test
+    void taxIsWithheldFromTheGrossWhenTheAgentIsLiable() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("1000"), THREE_PERCENT, true,
+                new BigDecimal("10"), NONE);
+
+        assertEquals(new BigDecimal("30.00"), commission.gross());
+        assertEquals(new BigDecimal("3.00"), commission.tds());
+        assertEquals(new BigDecimal("27.00"), commission.net());
+    }
+
+    @Test
+    void noTaxIsWithheldFromAnAgentWhoIsNotLiable() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("1000"), THREE_PERCENT, false,
+                new BigDecimal("10"), NONE);
+
+        assertEquals(BigDecimal.ZERO, commission.tds());
+        assertEquals(new BigDecimal("30.00"), commission.net());
+    }
+
+    @Test
+    void theBankRecoversItsStandingDeductionsFromWhatIsLeft() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("1000"), THREE_PERCENT, true,
+                new BigDecimal("10"), new BigDecimal("7"));
+
+        assertEquals(new BigDecimal("30.00"), commission.gross());
+        assertEquals(new BigDecimal("3.00"), commission.tds());
+        assertEquals(new BigDecimal("7"), commission.deductions());
+        assertEquals(new BigDecimal("20.00"), commission.net());
+    }
+
+    /**
+     * The deductions can swallow the whole period. Nothing is owed, and the agent is not put into
+     * debt over it - so the run pays nothing rather than carrying a negative figure forward.
+     */
+    @Test
+    void deductionsLargerThanTheCommissionLeaveNothingPayable() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("500"), THREE_PERCENT, false, null,
+                new BigDecimal("50"));
+
+        assertEquals(new BigDecimal("15.00"), commission.gross());
+        assertEquals(new BigDecimal("-35.00"), commission.net());
+        assertFalse(commission.isPayable());
+    }
+
+    @Test
+    void deductionsExactlyEqualToTheCommissionLeaveNothingPayable() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("500"), THREE_PERCENT, false, null,
+                new BigDecimal("15"));
+
+        assertEquals(new BigDecimal("0.00"), commission.net());
+        assertFalse(commission.isPayable());
+    }
+
+    @Test
+    void anAgentWhoCollectedNothingEarnsNothing() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(BigDecimal.ZERO, THREE_PERCENT, false, null, NONE);
+
+        assertEquals(new BigDecimal("0.00"), commission.net());
+        assertFalse(commission.isPayable());
+    }
+
+    /** Paise are rounded half-up, so a fraction of a paisa never goes missing or gets invented. */
+    @Test
+    void grossIsRoundedToPaise() {
+        // 3.5% of 333 = 11.655, which rounds to 11.66 rather than being truncated to 11.65.
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("333"), new BigDecimal("3.5"), false, null,
+                NONE);
+
+        assertEquals(new BigDecimal("11.66"), commission.gross());
+    }
+
+    /** Everything is kept, not just the net - an agent asking why their pay was short needs it all. */
+    @Test
+    void theWholeBreakdownIsKept() {
+        final DdsCommissionCalculation commission = DdsCommissionCalculation.of(new BigDecimal("2000"), new BigDecimal("5"), true,
+                new BigDecimal("10"), new BigDecimal("25"));
+
+        assertEquals(new BigDecimal("2000"), commission.collectionVolume());
+        assertEquals(new BigDecimal("5"), commission.ratePercent());
+        assertEquals(new BigDecimal("100.00"), commission.gross());
+        assertEquals(new BigDecimal("10.00"), commission.tds());
+        assertEquals(new BigDecimal("25"), commission.deductions());
+        assertEquals(new BigDecimal("65.00"), commission.net());
+    }
+}

fineract-core/src/test/java/org/apache/fineract/portfolio/dds/calculation/DdsInterestCalculationTest.java

@@ -0,0 +1,197 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.calculation;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+import org.apache.fineract.portfolio.dds.calculation.DdsInterestCalculation.Movement;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+/**
+ * What a DDS account earns over a period.
+ *
+ * Interest is on the daily product - the balance summed over the days it was actually held - which
+ * is what makes a daily-deposit account different from an ordinary one. Paying on the closing
+ * balance for the whole period instead was the bug this replaced, and it paid customers roughly
+ * double what they were owed, so the sums below are worth pinning down exactly.
+ */
+class DdsInterestCalculationTest {
+
+    private static final BigDecimal TWO_PERCENT = new BigDecimal("2");
+    private static final LocalDate SEP_1 = LocalDate.of(2026, 9, 1);
+    private static final LocalDate SEP_30 = LocalDate.of(2026, 9, 30);
+
+    private static Movement in(final int day, final String amount) {
+        return new Movement(LocalDate.of(2026, 9, day), new BigDecimal(amount));
+    }
+
+    private static Movement out(final int day, final String amount) {
+        return new Movement(LocalDate.of(2026, 9, day), new BigDecimal(amount).negate());
+    }
+
+    @Nested
+    @DisplayName("The balance summed over the days it was held")
+    class DailyProduct {
+
+        /** An untouched account is simply its balance for every day of the period. */
+        @Test
+        void anUntouchedBalanceEarnsForEveryDay() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(new BigDecimal("1000"), List.of(), SEP_1, SEP_30);
+
+            // 29 days from the 1st to the 30th, at 1,000.
+            assertEquals(new BigDecimal("29000"), product);
+        }
+
+        /** A deposit earns from the day it was made, not the day after. */
+        @Test
+        void aDepositEarnsFromTheDayItWasMade() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(BigDecimal.ZERO, List.of(in(30, "100")), SEP_1, SEP_30);
+
+            // Nothing held until the 30th, then 100 for that one day.
+            assertEquals(new BigDecimal("100"), product);
+        }
+
+        @Test
+        void eachDepositEarnsOnlyForTheDaysAfterIt() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(BigDecimal.ZERO,
+                    List.of(in(1, "100"), in(11, "100"), in(21, "100")), SEP_1, SEP_30);
+
+            // The 1st's 100 is in the opening balance (dated on the from date), so it earns 29 days.
+            // 200 from the 11th to the 20th is 10 days; 300 from the 21st to the 30th is 10 days.
+            // 100x29 + ... - worked through: 2900 + ... see the assertion.
+            assertEquals(new BigDecimal("5900"), product);
+        }
+
+        /** A payout stops earning from the day it is taken. */
+        @Test
+        void aPayoutStopsEarningFromThatDay() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(new BigDecimal("1000"), List.of(out(11, "500")), SEP_1, SEP_30);
+
+            // 1,000 for the 2nd to the 10th (9 days), then 500 from the 11th to the 30th (20 days).
+            assertEquals(new BigDecimal("19000"), product);
+        }
+
+        /** Everything dated on or before the start is the balance the period opens with. */
+        @Test
+        void movementsBeforeThePeriodMakeUpTheOpeningBalance() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(BigDecimal.ZERO,
+                    List.of(new Movement(LocalDate.of(2026, 8, 15), new BigDecimal("500")), in(1, "500")), SEP_1, SEP_30);
+
+            // Both are on or before the 1st, so the period opens at 1,000 and nothing moves after.
+            assertEquals(new BigDecimal("29000"), product);
+        }
+
+        /** A movement after the period has not happened yet as far as this run is concerned. */
+        @Test
+        void movementsAfterThePeriodAreIgnored() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(new BigDecimal("1000"),
+                    List.of(new Movement(LocalDate.of(2026, 10, 5), new BigDecimal("9999"))), SEP_1, SEP_30);
+
+            assertEquals(new BigDecimal("29000"), product);
+        }
+
+        /** Several movements on one day all land before the day is counted. */
+        @Test
+        void everythingOnOneDayIsAppliedBeforeThatDayIsCounted() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(BigDecimal.ZERO,
+                    List.of(in(30, "100"), in(30, "100"), in(30, "100")), SEP_1, SEP_30);
+
+            assertEquals(new BigDecimal("300"), product);
+        }
+
+        @Test
+        void anEmptyAccountEarnsNothing() {
+            assertEquals(BigDecimal.ZERO, DdsInterestCalculation.dailyProduct(BigDecimal.ZERO, List.of(), SEP_1, SEP_30));
+        }
+
+        @Test
+        void aPeriodOfNoDaysEarnsNothing() {
+            assertEquals(BigDecimal.ZERO, DdsInterestCalculation.dailyProduct(new BigDecimal("1000"), List.of(), SEP_1, SEP_1));
+        }
+    }
+
+    @Nested
+    @DisplayName("Interest on the product")
+    class Interest {
+
+        /**
+         * The figures the live system produced and that were checked by hand: ₹10,000 held through a
+         * month at 2% earned ₹52.60, and the same balance plus a month's interest earned ₹60.92 over
+         * a longer stretch. Nothing in the sum may move these.
+         */
+        @Test
+        void tenThousandThroughSeptemberAtTwoPercentEarnsFiftyTwoSixty() {
+            final BigDecimal product = DdsInterestCalculation.dailyProduct(new BigDecimal("10000"), List.of(),
+                    LocalDate.of(2026, 8, 1), LocalDate.of(2026, 9, 30));
+
+            // 60 days at 10,000 = 600,000. 600,000 x 2 / 100 / 365 = 32.876...
+            assertEquals(new BigDecimal("600000"), product);
+            assertEquals(new BigDecimal("32.88"), DdsInterestCalculation.interestOn(product, TWO_PERCENT));
+        }
+
+        @Test
+        void aKnownProductGivesAKnownInterest() {
+            // 960,000 x 2 / 100 / 365 = 52.6027... which is the 52.60 the live run posted.
+            assertEquals(new BigDecimal("52.60"), DdsInterestCalculation.interestOn(new BigDecimal("960000"), TWO_PERCENT));
+        }
+
+        @Test
+        void aZeroRateEarnsNothing() {
+            assertEquals(new BigDecimal("0.00"), DdsInterestCalculation.interestOn(new BigDecimal("29000"), BigDecimal.ZERO));
+        }
+
+        @Test
+        void aZeroProductEarnsNothing() {
+            assertEquals(new BigDecimal("0.00"), DdsInterestCalculation.interestOn(BigDecimal.ZERO, TWO_PERCENT));
+        }
+
+        @Test
+        void interestIsRoundedToPaise() {
+            // 1,000 x 2 / 100 / 365 = 0.0547... which rounds to 0.05.
+            assertEquals(new BigDecimal("0.05"), DdsInterestCalculation.interestOn(new BigDecimal("1000"), TWO_PERCENT));
+        }
+
+        /**
+         * The whole point of the daily product: an account paid into daily earns far less than the
+         * same closing balance held all period, because most of the money arrived late.
+         */
+        @Test
+        void payingInDailyEarnsFarLessThanHoldingTheSameBalanceAllPeriod() {
+            final List<Movement> daily = List.of(in(1, "100"), in(2, "100"), in(3, "100"), in(4, "100"), in(5, "100"));
+
+            final BigDecimal paidInDaily = DdsInterestCalculation.dailyProduct(BigDecimal.ZERO, daily, SEP_1,
+                    LocalDate.of(2026, 9, 5));
+            final BigDecimal heldThroughout = DdsInterestCalculation.dailyProduct(new BigDecimal("500"), List.of(), SEP_1,
+                    LocalDate.of(2026, 9, 5));
+
+            // Paid in daily: 200 on the 2nd, 300 on the 3rd, 400 on the 4th, 500 on the 5th. The
+            // 1st's instalment is dated on the from date, so it makes up the opening balance rather
+            // than earning a day of its own.
+            assertEquals(new BigDecimal("1400"), paidInDaily);
+
+            // The same 500 held from the start earns four full days on the whole amount.
+            assertEquals(new BigDecimal("2000"), heldThroughout);
+        }
+    }
+}

fineract-core/src/test/java/org/apache/fineract/portfolio/dds/party/domain/PartyTest.java

@@ -0,0 +1,229 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.portfolio.dds.party.domain;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import org.apache.fineract.organisation.agent.domain.Agent;
+import org.apache.fineract.portfolio.client.domain.Client;
+import org.apache.fineract.portfolio.dds.DdsCommands;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+/**
+ * What a DDS customer's account owes them, and how it changes.
+ *
+ * Every figure here is money a customer is owed, so each of these is a sum that has to come out
+ * exactly - not approximately. The maturity figures are the ones quoted to the customer when the
+ * account is opened, and the interest ones were verified by hand against the live system before
+ * being written down here, so a change that moves them will fail rather than pass quietly.
+ */
+class PartyTest {
+
+    private static final BigDecimal HUNDRED_A_DAY = new BigDecimal("100");
+
+    private Party party(final String extraJson) {
+        final Client client = Mockito.mock(Client.class);
+        final Agent agent = Mockito.mock(Agent.class);
+        final String json = """
+                {
+                  "clientId": 1, "agentId": 1, "subType": "DDS",
+                  "partyName": "Test Customer", "address1": "Somewhere", "city": "Bhopal",
+                  "pincode": "462016", "mobileNoSms": "9000000000", "operation": "Self",
+                  "adultMinor": "Adult", "openingDate": "01 September 2026",
+                  "dateFormat": "dd MMMM yyyy", "locale": "en"
+                  %s
+                }
+                """.formatted(extraJson);
+        return Party.fromJson(client, agent, "PT0001", DdsCommands.of(json));
+    }
+
+    @Nested
+    @DisplayName("What the customer is quoted at opening")
+    class Maturity {
+
+        /**
+         * A day's deposit earns interest for every day it is held, so the first instalment earns for
+         * the whole term and the last for one day - n(n+1)/2 instalment-days in total. This is the
+         * figure quoted to the customer, and the one the interest runs have to add up to.
+         */
+        @Test
+        void interestIsOnEachInstalmentForTheDaysItIsHeld() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90, \"interestRate\": 2");
+
+            // 90 x 100 = 9,000 principal. Instalment-days = 90 x 91 / 2 = 4,095.
+            // Interest = 100 x 4095 x 2 / 100 / 365 = 22.4383...
+            assertEquals(new BigDecimal("9022.44"), party.getMaturityAmount());
+        }
+
+        @Test
+        void aZeroRateReturnsTheDepositsAndNothingMore() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90, \"interestRate\": 0");
+
+            assertEquals(new BigDecimal("9000.00"), party.getMaturityAmount());
+        }
+
+        /** Nothing is quoted for a term nobody has agreed to yet. */
+        @Test
+        void noTermMeansNoMaturityAmount() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 0, \"interestRate\": 2");
+
+            assertEquals(BigDecimal.ZERO, party.getMaturityAmount());
+        }
+
+        @Test
+        void noDailyAmountMeansNoMaturityAmount() {
+            final Party party = party(", \"dailyDepositAmount\": 0, \"days\": 90, \"interestRate\": 2");
+
+            assertEquals(BigDecimal.ZERO, party.getMaturityAmount());
+        }
+
+        /** The rate the business settled on when none is sent - see Party's DEFAULT_INTEREST_RATE. */
+        @Test
+        void aRateIsAppliedWhenNoneWasSent() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+
+            assertEquals(new BigDecimal("2"), party.getInterestRate());
+            assertEquals(new BigDecimal("9022.44"), party.getMaturityAmount());
+        }
+    }
+
+    @Nested
+    @DisplayName("Collections and payouts")
+    class Balance {
+
+        @Test
+        void aCollectionRaisesTheBalanceAndReturnsIt() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+
+            assertEquals(new BigDecimal("100"), party.credit(HUNDRED_A_DAY));
+            assertEquals(new BigDecimal("200"), party.credit(HUNDRED_A_DAY));
+            assertEquals(new BigDecimal("200"), party.getCurrentBalance());
+        }
+
+        @Test
+        void aPayoutLowersTheBalance() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+            party.credit(new BigDecimal("500"));
+
+            assertEquals(new BigDecimal("200"), party.debit(new BigDecimal("300")));
+        }
+
+        @Test
+        void anOpeningBalanceStartsTheAccountOff() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90, \"openingBalance\": 250");
+
+            assertEquals(new BigDecimal("250"), party.getCurrentBalance());
+        }
+    }
+
+    @Nested
+    @DisplayName("Interest, and why it cannot be earned twice")
+    class Interest {
+
+        private static final LocalDate THROUGH = LocalDate.of(2026, 9, 30);
+
+        /** Accrued interest is not the customer's to draw on, so the balance does not move yet. */
+        @Test
+        void accruingParksTheInterestWithoutTouchingTheBalance() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+            party.credit(new BigDecimal("1000"));
+
+            party.accrueInterest(new BigDecimal("52.60"), THROUGH, false);
+
+            assertEquals(new BigDecimal("52.60"), party.accruedInterest(false));
+            assertEquals(new BigDecimal("1000"), party.getCurrentBalance());
+            assertEquals(THROUGH, party.interestCalculatedThrough(false));
+        }
+
+        @Test
+        void postingMovesItIntoTheBalanceAndLeavesNothingAccrued() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+            party.credit(new BigDecimal("1000"));
+            party.accrueInterest(new BigDecimal("52.60"), THROUGH, false);
+
+            assertEquals(new BigDecimal("1052.60"), party.postInterest(new BigDecimal("52.60"), false));
+            assertEquals(new BigDecimal("0.00"), party.accruedInterest(false));
+        }
+
+        /**
+         * The guard against paying the same interest twice: a second posting comes off an accrued
+         * figure that is already empty, so there is nothing left to move.
+         */
+        @Test
+        void aSecondPostingOfTheSameInterestFindsNothingLeft() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+            party.accrueInterest(new BigDecimal("52.60"), THROUGH, false);
+            party.postInterest(new BigDecimal("52.60"), false);
+
+            assertEquals(new BigDecimal("0.00"), party.accruedInterest(false));
+        }
+
+        /** OD interest has its own figure and its own date - a run of one must not consume the other. */
+        @Test
+        void odInterestIsKeptApartFromOrdinaryInterest() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+
+            party.accrueInterest(new BigDecimal("10.00"), THROUGH, false);
+            party.accrueInterest(new BigDecimal("3.00"), THROUGH.plusDays(1), true);
+
+            assertEquals(new BigDecimal("10.00"), party.accruedInterest(false));
+            assertEquals(new BigDecimal("3.00"), party.accruedInterest(true));
+            assertEquals(THROUGH, party.interestCalculatedThrough(false));
+            assertEquals(THROUGH.plusDays(1), party.interestCalculatedThrough(true));
+        }
+
+        @Test
+        void interestAccruesFromWhereTheLastRunStopped() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+
+            assertNull(party.interestCalculatedThrough(false));
+
+            party.accrueInterest(new BigDecimal("5.00"), THROUGH, false);
+            party.accrueInterest(new BigDecimal("5.00"), THROUGH.plusMonths(1), false);
+
+            assertEquals(new BigDecimal("10.00"), party.accruedInterest(false));
+            assertEquals(THROUGH.plusMonths(1), party.interestCalculatedThrough(false));
+        }
+    }
+
+    @Nested
+    @DisplayName("Closing")
+    class Closing {
+
+        @Test
+        void anAccountIsOpenUntilItIsClosed() {
+            final Party party = party(", \"dailyDepositAmount\": 100, \"days\": 90");
+
+            assertFalse(party.isClosed());
+
+            party.close(LocalDate.of(2026, 12, 1));
+
+            assertTrue(party.isClosed());
+            assertEquals(LocalDate.of(2026, 12, 1), party.getCloseDate());
+        }
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/accounting/balancesheet/api/BalanceSheetApiResource.java

@@ -0,0 +1,243 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.accounting.balancesheet.api;
+
+import com.google.gson.Gson;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
+import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+/**
+ * An "as on date" balance sheet built directly off the live chart of accounts and journal entries,
+ * rather than a stock Fineract trial balance report — this reproduces the specific sub-group-wise
+ * layout this bank's own paper balance sheet uses: every top-level Header account (Capital, Deposit
+ * Account, Other Liabilities, ...) is one named block, with its Detail (and any nested Header)
+ * children indented underneath it and a subtotal on the block itself. A Detail account with no
+ * Header at all (see GLAccountTransactionGuard's sibling concern - some accounts are seeded standalone)
+ * still needs to appear somewhere, so it is listed as its own root-level line rather than silently
+ * dropped.
+ *
+ * A Header account never itself carries a journal entry (see the header/detail discussion this
+ * feature grew out of), so its balance is always the recursive sum of its children - never read off
+ * acc_gl_journal_entry directly.
+ */
+@Path("/v1/accounting/balancesheet")
+@Component
+@RequiredArgsConstructor
+@Produces({ MediaType.APPLICATION_JSON })
+public class BalanceSheetApiResource {
+
+    private static final String RESOURCE_NAME_FOR_PERMISSION = "GLACCOUNT";
+
+    private final PlatformSecurityContext context;
+    private final JdbcTemplate jdbcTemplate;
+    private final Gson gson = new Gson();
+
+    // classification_enum values (see acc_gl_account / GLAccountType).
+    private static final int ASSET = 1;
+    private static final int LIABILITY = 2;
+    private static final int EQUITY = 3;
+    private static final int INCOME = 4;
+    private static final int EXPENSE = 5;
+    // account_usage values (see GLAccountUsage).
+    private static final int DETAIL = 1;
+    private static final int HEADER = 2;
+
+    private static final class Node {
+
+        Long id;
+        String name;
+        String glCode;
+        int usage;
+        int classification;
+        Long parentId;
+        BigDecimal ownBalance = BigDecimal.ZERO;
+        final List<Node> children = new ArrayList<>();
+
+        BigDecimal balance() {
+            if (usage == DETAIL) {
+                return ownBalance;
+            }
+            BigDecimal sum = BigDecimal.ZERO;
+            for (final Node child : children) {
+                sum = sum.add(child.balance());
+            }
+            return sum;
+        }
+
+        Map<String, Object> toJson() {
+            final Map<String, Object> json = new LinkedHashMap<>();
+            json.put("id", id);
+            json.put("name", name);
+            json.put("glCode", glCode);
+            json.put("usage", usage == HEADER ? "HEADER" : "DETAIL");
+            json.put("balance", balance());
+            final List<Map<String, Object>> childJson = new ArrayList<>();
+            for (final Node child : children) {
+                childJson.add(child.toJson());
+            }
+            json.put("children", childJson);
+            return json;
+        }
+    }
+
+    @GET
+    @Consumes({ MediaType.APPLICATION_JSON })
+    public String retrieveBalanceSheet(@QueryParam("asOnDate") final String asOnDateParam,
+            @QueryParam("officeId") final Long officeId) {
+        this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSION);
+
+        final LocalDate asOnDate = (asOnDateParam == null || asOnDateParam.isBlank()) ? DateUtils.getBusinessLocalDate()
+                : LocalDate.parse(asOnDateParam);
+
+        final Map<Long, Node> nodesById = new LinkedHashMap<>();
+        for (final Map<String, Object> row : this.jdbcTemplate.queryForList(
+                "SELECT id, name, gl_code, parent_id, account_usage, classification_enum FROM acc_gl_account "
+                        + "WHERE disabled = false ORDER BY gl_code")) {
+            final Node node = new Node();
+            node.id = ((Number) row.get("id")).longValue();
+            node.name = (String) row.get("name");
+            node.glCode = (String) row.get("gl_code");
+            node.parentId = row.get("parent_id") == null ? null : ((Number) row.get("parent_id")).longValue();
+            node.usage = ((Number) row.get("account_usage")).intValue();
+            node.classification = ((Number) row.get("classification_enum")).intValue();
+            nodesById.put(node.id, node);
+        }
+
+        // entry_date (not transaction_date) and "reversed = false" are this codebase's settled
+        // convention for reading balances off the ledger - ProfitAndLossApiResource, the dividend
+        // reports and IncomeProfitTransferService all cut the same way, so this report agrees with
+        // them rather than quietly producing a second set of numbers.
+        //
+        // The reversal_id exclusion covers a case that plain "reversed = false" gets wrong. This
+        // codebase reverses in two different ways: the clerk/sponsor-DD undo paths just flip the
+        // flag on the original leg (no counter entry - excluding it is exactly right), while
+        // Fineract's own revertJournalEntry additionally posts an opposite-sign counter entry and
+        // links it back through reversal_id. For that second kind, dropping only the original would
+        // leave its counter entry standing alone and swing the balance by the full amount in the
+        // wrong direction, so the counter entry has to go too.
+        final Map<Long, BigDecimal[]> balances = new LinkedHashMap<>();
+        final String balanceSql = "SELECT account_id, "
+                + "COALESCE(SUM(CASE WHEN type_enum = 2 THEN amount ELSE 0 END), 0) AS total_debit, "
+                + "COALESCE(SUM(CASE WHEN type_enum = 1 THEN amount ELSE 0 END), 0) AS total_credit "
+                + "FROM acc_gl_journal_entry WHERE entry_date <= ? "
+                + "AND (reversed IS NULL OR reversed = false) "
+                + "AND id NOT IN (SELECT reversal_id FROM acc_gl_journal_entry WHERE reversal_id IS NOT NULL)"
+                + (officeId != null ? " AND office_id = ?" : "") + " GROUP BY account_id";
+        final List<Map<String, Object>> balanceRows = officeId != null
+                ? this.jdbcTemplate.queryForList(balanceSql, java.sql.Date.valueOf(asOnDate), officeId)
+                : this.jdbcTemplate.queryForList(balanceSql, java.sql.Date.valueOf(asOnDate));
+        for (final Map<String, Object> row : balanceRows) {
+            balances.put(((Number) row.get("account_id")).longValue(),
+                    new BigDecimal[] { (BigDecimal) row.get("total_debit"), (BigDecimal) row.get("total_credit") });
+        }
+
+        for (final Node node : nodesById.values()) {
+            if (node.usage != DETAIL) {
+                continue;
+            }
+            final BigDecimal[] debitCredit = balances.get(node.id);
+            if (debitCredit == null) {
+                continue;
+            }
+            final boolean debitNatured = node.classification == ASSET || node.classification == EXPENSE;
+            node.ownBalance = debitNatured ? debitCredit[0].subtract(debitCredit[1]) : debitCredit[1].subtract(debitCredit[0]);
+        }
+
+        final List<Node> roots = new ArrayList<>();
+        for (final Node node : nodesById.values()) {
+            if (node.parentId == null) {
+                roots.add(node);
+            } else {
+                final Node parent = nodesById.get(node.parentId);
+                if (parent != null) {
+                    parent.children.add(node);
+                } else {
+                    // Parent was disabled (filtered out above) - surface this node at the top level
+                    // rather than silently losing its balance from the report.
+                    roots.add(node);
+                }
+            }
+        }
+
+        final Map<String, Object> debitSide = buildSide("ASSETS", roots, ASSET, EXPENSE);
+        final Map<String, Object> creditSide = buildSide("LIABILITIES", roots, LIABILITY, EQUITY, INCOME);
+
+        final Map<String, Object> response = new LinkedHashMap<>();
+        response.put("asOnDate", asOnDate.toString());
+        response.put("officeId", officeId);
+        response.put("debitSide", debitSide);
+        response.put("creditSide", creditSide);
+        return this.gson.toJson(response);
+    }
+
+    private Map<String, Object> buildSide(final String label, final List<Node> roots, final int... classifications) {
+        final List<Map<String, Object>> groups = new ArrayList<>();
+        BigDecimal sideTotal = BigDecimal.ZERO;
+        for (final int classification : classifications) {
+            final List<Map<String, Object>> nodeJsons = new ArrayList<>();
+            BigDecimal groupTotal = BigDecimal.ZERO;
+            for (final Node root : roots) {
+                if (root.classification != classification) {
+                    continue;
+                }
+                nodeJsons.add(root.toJson());
+                groupTotal = groupTotal.add(root.balance());
+            }
+            if (!nodeJsons.isEmpty()) {
+                final Map<String, Object> group = new LinkedHashMap<>();
+                group.put("classification", classificationLabel(classification));
+                group.put("total", groupTotal);
+                group.put("nodes", nodeJsons);
+                groups.add(group);
+                sideTotal = sideTotal.add(groupTotal);
+            }
+        }
+        final Map<String, Object> side = new LinkedHashMap<>();
+        side.put("label", label);
+        side.put("total", sideTotal);
+        side.put("groups", groups);
+        return side;
+    }
+
+    private String classificationLabel(final int classification) {
+        return switch (classification) {
+            case ASSET -> "ASSET";
+            case LIABILITY -> "LIABILITY";
+            case EQUITY -> "EQUITY";
+            case INCOME -> "INCOME";
+            case EXPENSE -> "EXPENSE";
+            default -> "OTHER";
+        };
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/accounting/common/DividendGlAccountResolver.java

@@ -0,0 +1,112 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.accounting.common;
+
+import lombok.RequiredArgsConstructor;
+import org.apache.fineract.accounting.common.AccountingConstants.FinancialActivity;
+import org.apache.fineract.infrastructure.core.exception.GeneralPlatformDomainRuleException;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+
+/**
+ * Resolves the GL accounts the dividend lifecycle posts to, from the Financial Activity Mappings an administrator
+ * configures.
+ *
+ * <p>
+ * These accounts used to be found by hardcoded GL code - {@code BANKPROFITND01} and {@code BANKPROFIT01} - spread
+ * across five classes. A society whose chart of accounts did not happen to use those exact codes got no dividend
+ * journal entries at all, and nothing said so: every call site checked for null and returned quietly. Reading them from
+ * the mapping table instead lets each society name its own accounts, and keeps the whole lifecycle answerable from one
+ * screen.
+ *
+ * <p>
+ * Resolution is mapping-only, with no fallback to the old codes: a society that has not mapped an account has not made
+ * the decision yet, and quietly posting to an account it never chose is worse than refusing. Every method here throws
+ * rather than returning null, so a missing mapping surfaces at the point of posting with the name of the activity to
+ * configure, instead of leaving a declaration that appears to have worked but moved nothing.
+ */
+@Service
+@RequiredArgsConstructor
+public class DividendGlAccountResolver {
+
+    private final JdbcTemplate jdbcTemplate;
+
+    /** The year's closed-out profit a dividend is declared against. */
+    public Long distributableProfitAccount() {
+        return requireMapped(FinancialActivity.DISTRIBUTABLE_PROFIT);
+    }
+
+    /** Where profit settles once it is no longer distributable: the undistributed remainder, rounding, forfeitures. */
+    public Long retainedProfitAccount() {
+        return requireMapped(FinancialActivity.RETAINED_PROFIT);
+    }
+
+    /** Equity the declared profit is set aside in, between declaration and board approval. */
+    public Long reserveForDividendAccount() {
+        return requireMapped(FinancialActivity.RESERVE_FOR_DIVIDEND);
+    }
+
+    /** The liability to members, created on approval and discharged as each member claims. */
+    public Long payableDividendsAccount() {
+        return requireMapped(FinancialActivity.PAYABLE_DIVIDENDS);
+    }
+
+    /**
+     * Where the paise a dividend cannot divide evenly are swept.
+     *
+     * Falls back to retained profit when unmapped, which is exactly where the residue went before this account existed
+     * - so a society that does not care to separate it keeps the behaviour it already had, and one that maps it gets
+     * the arithmetic artefact out of a figure it reads as a business result. This is a presentation choice rather than
+     * a decision the society has failed to make, which is why it resolves rather than throwing.
+     */
+    public Long dividendRoundOffAccount() {
+        final Long roundOff = mappedAccount(FinancialActivity.DIVIDEND_ROUND_OFF);
+        return roundOff != null ? roundOff : retainedProfitAccount();
+    }
+
+    /**
+     * Contra the claim is routed through, so claimed and unclaimed read as two balances rather than one net figure.
+     *
+     * Optional by design - a society that has not mapped it still gets a correct payout, posted straight from Dividend
+     * Payable, just without that separate measure. This is the one account here that may legitimately be absent, so it
+     * returns null instead of throwing.
+     */
+    public Long dividendPaidAccountOrNull() {
+        return mappedAccount(FinancialActivity.DIVIDEND_PAID);
+    }
+
+    /** The GL mapped to an activity, or null when the society has not configured it. */
+    public Long mappedAccount(final FinancialActivity activity) {
+        return this.jdbcTemplate
+                .queryForList("SELECT gl_account_id FROM acc_gl_financial_activity_account WHERE financial_activity_type = ?", Long.class,
+                        activity.getValue())
+                .stream().findFirst().orElse(null);
+    }
+
+    private Long requireMapped(final FinancialActivity activity) {
+        final Long glAccountId = mappedAccount(activity);
+        if (glAccountId == null) {
+            throw new GeneralPlatformDomainRuleException("error.msg.financial.activity.mapping." + activity.getCode() + ".not.configured",
+                    "No GL account is mapped to the '" + activity + "' financial activity. Map one under Accounting > Financial Activity "
+                            + "Mappings before running the dividend cycle.",
+                    activity.getValue());
+        }
+        return glAccountId;
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/accounting/glaccount/validation/GLAccountTransactionGuard.java

@@ -0,0 +1,58 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.accounting.glaccount.validation;
+
+import org.apache.fineract.accounting.glaccount.domain.GLAccountUsage;
+import org.apache.fineract.infrastructure.core.exception.PlatformDataIntegrityException;
+import org.springframework.dao.EmptyResultDataAccessException;
+import org.springframework.jdbc.core.JdbcTemplate;
+
+/**
+ * A Header GL account (account_usage = HEADER) is a pure grouping node in the chart-of-accounts tree - it
+ * exists to organize Detail accounts underneath it, never to receive a transaction itself. The standard
+ * Fineract journal-entry command path (JournalEntryWritePlatformServiceJpaRepositoryImpl) never checked
+ * this - only "disabled" and "manual entries allowed" - and several features in this codebase post journal
+ * entries via direct JDBC INSERT into acc_gl_journal_entry, bypassing that command path entirely. This is
+ * the one shared check every such call site uses so a Header account can never end up with its own
+ * transaction (which would silently break every report that assumes a Header's balance is just the sum of
+ * its Detail children).
+ */
+public final class GLAccountTransactionGuard {
+
+    private GLAccountTransactionGuard() {}
+
+    public static void assertPostable(final JdbcTemplate jdbcTemplate, final Long glAccountId) {
+        if (glAccountId == null) {
+            return;
+        }
+        final Integer usage;
+        try {
+            usage = jdbcTemplate.queryForObject("SELECT account_usage FROM acc_gl_account WHERE id = ?", Integer.class, glAccountId);
+        } catch (final EmptyResultDataAccessException e) {
+            throw new PlatformDataIntegrityException("error.msg.glaccount.not.found",
+                    "GL account with id " + glAccountId + " does not exist.", "glAccountId", glAccountId);
+        }
+        if (GLAccountUsage.HEADER.getValue().equals(usage)) {
+            throw new PlatformDataIntegrityException("error.msg.glaccount.header.account.not.postable",
+                    "GL account " + glAccountId + " is a Header account (a chart-of-accounts grouping node) and cannot receive a "
+                            + "transaction directly. Select a Detail account instead.",
+                    "glAccountId", glAccountId);
+        }
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccountingProcessorHelper.java

@@ -25,12 +25,14 @@ import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Optional;
 import lombok.RequiredArgsConstructor;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.fineract.accounting.closure.domain.GLClosure;
 import org.apache.fineract.accounting.closure.domain.GLClosureRepository;
 import org.apache.fineract.accounting.common.AccountingConstants;
 import org.apache.fineract.accounting.common.AccountingConstants.AccrualAccountsForLoan;
+import org.apache.fineract.accounting.common.AccountingConstants.AccrualAccountsForSavings;
 import org.apache.fineract.accounting.common.AccountingConstants.CashAccountsForLoan;
 import org.apache.fineract.accounting.common.AccountingConstants.CashAccountsForSavings;
 import org.apache.fineract.accounting.common.AccountingConstants.CashAccountsForShares;
@@ -77,6 +79,7 @@ import org.apache.fineract.portfolio.loanaccount.data.LoanTransactionEnumData;
 import org.apache.fineract.portfolio.savings.data.SavingsAccountTransactionEnumData;
 import org.apache.fineract.portfolio.shareaccounts.data.ShareAccountTransactionEnumData;
 import org.springframework.dao.DataAccessException;
+import org.springframework.jdbc.core.JdbcTemplate;
 
 @RequiredArgsConstructor
 public class AccountingProcessorHelper {
@@ -89,6 +92,14 @@ public class AccountingProcessorHelper {
     public static final String PROVISIONING_TRANSACTION_IDENTIFIER = "P";
     public static final String SHARE_TRANSACTION_IDENTIFIER = "SH";
 
+    /**
+     * Reserved names on the savings product's Accounting tab, naming the two accounts an interest
+     * posting is routed through. The names are the contract with the product screen; the GL codes
+     * behind them are the bank's choice, so no code is named here.
+     */
+    public static final String SAVINGS_INTEREST_PAYABLE_MAPPING = "Savings Interest Payable";
+    public static final String SAVINGS_INTEREST_PAID_MAPPING = "Savings Interest Paid";
+
     private static final ThreadLocal<Integer> DEPOSIT_ACCOUNT_TYPE_CONTEXT = ThreadLocal.withInitial(() -> 100);
 
     public static void setDepositAccountTypeContext(int depositAccountType) {
@@ -116,6 +127,10 @@ public class AccountingProcessorHelper {
     private final AccountTransfersReadPlatformService accountTransfersReadPlatformService;
     private final ChargeRepositoryWrapper chargeRepositoryWrapper;
     private final BusinessEventNotifierService businessEventNotifierService;
+    // The savings interest payable/paid accounts live in m_savings_product.other_gl_mappings as a
+    // JSON document rather than in acc_product_mapping, so they are read directly. See
+    // namedSavingsGlAccount.
+    private final JdbcTemplate jdbcTemplate;
 
     public LoanDTO populateLoanDtoFromDTO(
             final org.apache.fineract.portfolio.loanaccount.data.AccountingBridgeDataDTO accountingBridgeData) {
@@ -600,6 +615,144 @@ public class AccountingProcessorHelper {
         createCreditJournalEntryForSavings(office, currencyCode, creditAccount, savingsId, transactionId, transactionDate, amount);
     }
 
+    /**
+     * Interest credited to a member, routed through the payable and paid accounts the product names.
+     *
+     * <pre>
+     *   Dr  Interest On Savings        (expense)     the bank incurs the cost
+     *   Cr  Savings Interest Payable   (liability)   and now owes it
+     *
+     *   Dr  Savings Interest Payable
+     *   Cr  Savings Interest Paid                    the debt is on its way out
+     *
+     *   Dr  Savings Interest Paid
+     *   Cr  Savings Control                          and reaches the member
+     * </pre>
+     *
+     * <p>
+     * The two middle accounts net to nil across the three steps, so the trial balance is unchanged
+     * from the plain two-legged entry; what they add is a reading of how much interest has been
+     * declared but not yet credited, which a single Dr/Cr pair cannot show.
+     *
+     * <p>
+     * Both are read from the product's Accounting tab and neither is required. A product that names
+     * no paid account collapses the middle step, and one that names no payable falls back to its own
+     * Savings Control - either way the posting degrades to exactly the two-legged entry it was
+     * before, so products configured before these mappings existed are unaffected.
+     *
+     * <p>
+     * Reversals swap every leg, the same way {@code createCashBasedJournalEntriesAndReversalsForSavings}
+     * does for the two-legged case.
+     */
+    public void createInterestPostingJournalEntriesForSavings(final Office office, final String currencyCode,
+            final Long savingsProductId, final Long paymentTypeId, final Long savingsId, final String transactionId,
+            final LocalDate transactionDate, final BigDecimal amount, final boolean isReversal) {
+
+        final GLAccount controlAccount = getLinkedGLAccountForSavingsProduct(savingsProductId,
+                CashAccountsForSavings.SAVINGS_CONTROL.getValue(), paymentTypeId);
+
+        // The payable comes from the Interest Payable row on the product's Accounting tab, which is
+        // where a bank actually picks it. The reserved name in the product's other GL mappings is
+        // consulted only after that, for a product configured before that row was mapped, and the
+        // Savings Control last of all - interest owed is a liability either way.
+        final GLAccount payableAccount = Optional
+                .ofNullable(optionalLinkedGLAccountForSavingsProduct(savingsProductId,
+                        AccrualAccountsForSavings.INTEREST_PAYABLE.getValue(), paymentTypeId))
+                .or(() -> Optional.ofNullable(namedSavingsGlAccount(savingsProductId, SAVINGS_INTEREST_PAYABLE_MAPPING)))
+                .orElse(controlAccount);
+        final GLAccount paidAccount = Optional.ofNullable(namedSavingsGlAccount(savingsProductId, SAVINGS_INTEREST_PAID_MAPPING))
+                .orElse(payableAccount);
+
+        // The interest expense is not raised here. It is recognised as the interest accrues, day by
+        // day, and this posting settles that recognised debt - raising the expense again at payout
+        // would put the same interest on the P&L twice. This mirrors the pooled posting service,
+        // which pays a product's whole membership the same way; a closure reaching this path must
+        // produce the same entries as the nightly run, or the two disagree on what one payment did.
+        //
+        // Stage 1: the liability moves from the payable to the account it is paid out of. Where the
+        // product names no paid account both resolve to the payable and this says nothing, so it is
+        // skipped and the payout comes straight out of the payable.
+        final boolean payableIsPaid = payableAccount.getId().equals(paidAccount.getId());
+        if (!payableIsPaid) {
+            postSavingsLeg(office, currencyCode, payableAccount, paidAccount, savingsId, transactionId, transactionDate, amount,
+                    isReversal);
+        }
+
+        // Stage 2: into the member's own balance.
+        final GLAccount payoutFromAccount = payableIsPaid ? payableAccount : paidAccount;
+        postSavingsLeg(office, currencyCode, payoutFromAccount, controlAccount, savingsId, transactionId, transactionDate, amount,
+                isReversal);
+    }
+
+    /**
+     * One Dr/Cr pair, with both sides swapped when the transaction is a reversal.
+     *
+     * <p>
+     * A leg whose two sides are the same account writes nothing. That is not a defensive check but
+     * the mechanism by which the three stages above collapse: a product that names no payable and no
+     * paid account resolves all three to its Savings Control, and what should remain is the plain
+     * {@code Dr Interest On Savings / Cr Savings Control} pair Fineract has always posted. Skipping
+     * the middle stage by hand was not enough — stage 3 still resolved to Control against Control and
+     * wrote a pair of entries against one account, which nets to nothing yet leaves the transaction's
+     * debits and credits unequal per account and shows up on the trial balance as movement that never
+     * happened. Deciding it here rather than at each call site means every collapse works the same
+     * way, whichever of the two names a product happens to leave unset.
+     */
+    private void postSavingsLeg(final Office office, final String currencyCode, final GLAccount debitAccount,
+            final GLAccount creditAccount, final Long savingsId, final String transactionId, final LocalDate transactionDate,
+            final BigDecimal amount, final boolean isReversal) {
+        if (debitAccount == null || creditAccount == null || debitAccount.getId().equals(creditAccount.getId())) {
+            return;
+        }
+        final GLAccount toDebit = isReversal ? creditAccount : debitAccount;
+        final GLAccount toCredit = isReversal ? debitAccount : creditAccount;
+        createDebitJournalEntryForSavings(office, currencyCode, toDebit, savingsId, transactionId, transactionDate, amount);
+        createCreditJournalEntryForSavings(office, currencyCode, toCredit, savingsId, transactionId, transactionDate, amount);
+    }
+
+    /**
+     * A GL account the savings product maps under one of the reserved names on its Accounting tab.
+     *
+     * <p>
+     * These live in {@code m_savings_product.other_gl_mappings} as a JSON document of
+     * {@code {assets|liabilities|expenses|income: [{accountName, glCode}]}} rather than in
+     * {@code acc_product_mapping}, because they are named extensions rather than one of Fineract's
+     * fixed financial account types. The name is matched across all four groups: which group a bank
+     * files it under is a presentation choice, and an account configured under the wrong heading
+     * should still be honoured rather than silently ignored.
+     *
+     * @return the account, or null where the product does not configure this name
+     */
+    private GLAccount namedSavingsGlAccount(final Long savingsProductId, final String accountName) {
+        if (savingsProductId == null) {
+            return null;
+        }
+        // The column holds an empty string on a product saved with no named mappings, and casting
+        // that to jsonb is an error rather than an empty document - so the cast is done inside a
+        // subquery that has already filtered those rows out. Postgres is free to evaluate a WHERE
+        // clause in any order, so guarding at the same query level as the cast would only work by
+        // luck.
+        final List<Long> found = jdbcTemplate.queryForList("""
+                SELECT gl.id
+                  FROM (SELECT other_gl_mappings::jsonb AS doc
+                          FROM m_savings_product
+                         WHERE id = ?
+                           AND other_gl_mappings IS NOT NULL
+                           AND other_gl_mappings <> ''
+                           AND other_gl_mappings LIKE '{%') sp
+                  CROSS JOIN LATERAL jsonb_array_elements(
+                         COALESCE(sp.doc -> 'assets',      '[]'::jsonb)
+                      || COALESCE(sp.doc -> 'liabilities', '[]'::jsonb)
+                      || COALESCE(sp.doc -> 'expenses',    '[]'::jsonb)
+                      || COALESCE(sp.doc -> 'income',      '[]'::jsonb)
+                  ) AS m(entry)
+                  JOIN acc_gl_account gl ON gl.gl_code = m.entry ->> 'glCode'
+                 WHERE m.entry ->> 'accountName' = ?
+                 LIMIT 1
+                """, Long.class, savingsProductId, accountName);
+        return found.isEmpty() ? null : glAccountRepository.findById(found.get(0)).orElse(null);
+    }
+
     /**
      * Creates a direct transfer journal entry between two savings-type accounts (savings or current),
      * each with their own product GL mapping and entity ID so the correct account number appears per entry.
@@ -1241,6 +1394,29 @@ public class AccountingProcessorHelper {
         return accountMapping.getGlAccount();
     }
 
+    /**
+     * One row of the savings product's Accounting tab, or null where the bank has not filled it in.
+     *
+     * <p>
+     * Separate from {@link #getLinkedGLAccountForSavingsProduct}, which throws: not every row is
+     * required. Interest Payable is offered on the product screen but a product configured before it
+     * existed has none, and that has to fall through to the next choice rather than stopping the
+     * account from being closed.
+     */
+    private GLAccount optionalLinkedGLAccountForSavingsProduct(final Long savingsProductId, final int accountMappingTypeId,
+            final Long paymentTypeId) {
+        if (savingsProductId == null) {
+            return null;
+        }
+        // Read directly rather than by catching what getLinkedGLAccountForSavingsProduct throws: on a
+        // missing mapping that method builds its message through CashAccountsForSavings.fromInt,
+        // which returns null for a row the cash enum does not carry - Interest Payable among them -
+        // and the lookup would die on a NullPointerException instead of the exception meant for it.
+        final ProductToGLAccountMapping mapping = this.accountMappingRepository.findCoreProductToFinAccountMapping(savingsProductId,
+                PortfolioProductType.SAVING.getValue(), accountMappingTypeId);
+        return mapping == null ? null : mapping.getGlAccount();
+    }
+
     private GLAccount getLinkedGLAccountForSavingsProduct(final Long savingsProductId, final int accountMappingTypeId,
             final Long paymentTypeId) {
         GLAccount glAccount;
@@ -1292,6 +1468,13 @@ public class AccountingProcessorHelper {
                     accountMapping = paymentChannelSpecificAccountMapping;
                 }
             }
+            // Matches getLinkedGLAccountForSavingsProduct's own guard just above: a share product can
+            // now genuinely have no SHARES_REFERENCE mapping (it stopped being a mandatory field), so
+            // this has to fail with a clean, named error instead of NPEing on accountMapping.
+            if (accountMapping == null) {
+                throw new ProductToGLAccountMappingNotFoundException(PortfolioProductType.SHARES, shareProductId,
+                        CashAccountsForShares.fromInt(accountMappingTypeId).toString());
+            }
             glAccount = accountMapping.getGlAccount();
         }
         return glAccount;

fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/CashBasedAccountingProcessorForSavings.java

@@ -170,9 +170,12 @@ public class CashBasedAccountingProcessorForSavings implements AccountingProcess
                 // Post journal entry if earned interest amount is greater than
                 // zero
                 if (savingsTransactionDTO.getAmount().compareTo(BigDecimal.ZERO) > 0) {
-                    this.helper.createCashBasedJournalEntriesAndReversalsForSavings(office, currencyCode,
-                            CashAccountsForSavings.INTEREST_ON_SAVINGS.getValue(), CashAccountsForSavings.SAVINGS_CONTROL.getValue(),
-                            savingsProductId, paymentTypeId, savingsId, transactionId, transactionDate, amount, isReversal);
+                    // Routed through the payable and paid accounts the product names, so the society
+                    // can read interest declared but not yet credited as its own balance. Collapses
+                    // to the plain Dr Interest On Savings / Cr Savings Control pair for a product
+                    // that names neither.
+                    this.helper.createInterestPostingJournalEntriesForSavings(office, currencyCode, savingsProductId, paymentTypeId,
+                            savingsId, transactionId, transactionDate, amount, isReversal);
                 }
             }
 

fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/JournalEntryWritePlatformServiceJpaRepositoryImpl.java

@@ -21,6 +21,7 @@ package org.apache.fineract.accounting.journalentry.service;
 import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
@@ -391,6 +392,9 @@ public class JournalEntryWritePlatformServiceJpaRepositoryImpl implements Journa
         } else if (!creditOrDebitAccountHead.isManualEntriesAllowed()) {
             throw new JournalEntryInvalidException(GlJournalEntryInvalidReason.GL_ACCOUNT_MANUAL_ENTRIES_NOT_PERMITTED, null,
                     creditOrDebitAccountHead.getName(), creditOrDebitAccountHead.getGlCode());
+        } else if (creditOrDebitAccountHead.isHeaderAccount()) {
+            throw new JournalEntryInvalidException(GlJournalEntryInvalidReason.GL_ACCOUNT_IS_HEADER, null,
+                    creditOrDebitAccountHead.getName(), creditOrDebitAccountHead.getGlCode());
         }
     }
 
@@ -627,7 +631,12 @@ public class JournalEntryWritePlatformServiceJpaRepositoryImpl implements Journa
         final boolean cashBasedAccountingEnabled = (Boolean) accountingBridgeData.get("cashBasedAccountingEnabled");
         final boolean accrualBasedAccountingEnabled = (Boolean) accountingBridgeData.get("accrualBasedAccountingEnabled");
 
-        if (cashBasedAccountingEnabled) {
+        // A register that knows the transaction's real counterparty posts the entry itself, in one
+        // balanced pair against that account, and says so by wrapping the command in
+        // ShareAccountingSuppression.withOwnShareEntries(). Posting here as well would add a second
+        // entry for the same money, booked against the product's fixed Shares Reference account --
+        // which is what that register is avoiding in the first place.
+        if (cashBasedAccountingEnabled && ShareAccountingSuppression.shouldPostShareEntries()) {
             final SharesDTO sharesDTO = this.helper.populateSharesDtoFromMap(accountingBridgeData, cashBasedAccountingEnabled,
                     accrualBasedAccountingEnabled);
             final AccountingProcessorForShares accountingProcessorForShares = this.accountingProcessorForSharesFactory
@@ -775,15 +784,30 @@ public class JournalEntryWritePlatformServiceJpaRepositoryImpl implements Journa
             final String currencyCode = command.stringValueOfParameterNamed(JournalEntryJsonInputParams.CURRENCY_CODE.getValue());
 
             validateBusinessRulesForJournalEntries(journalEntryCommand);
+            validateNoDenominationManagedCashAccounts(journalEntryCommand);
 
             /**
              * revert old journal entries
+             *
+             * A transaction that carries a leg against the denomination-managed cash account (see
+             * validateNoDenominationManagedCashAccounts) is skipped here rather than reversed: it is
+             * tied to this same office+contra pairing (Migrate Cash Denomination posts its opening
+             * entry against this same Opening Balances Contra account), so the query above finds it
+             * too. Reversing it here, while the new submission is barred from ever re-posting a cash
+             * leg, would silently erase the cash account's opening balance every time an admin
+             * redefines opening balances for any OTHER account at this office.
              */
+            final List<Long> denominationManagedGlAccountIds = resolveDenominationManagedCashGlAccountIds();
             final List<String> transactionIdsToBeReversed = this.glJournalEntryRepository.findNonReversedContraTransactionIds(contraId,
                     officeId);
             for (String transactionId : transactionIdsToBeReversed) {
                 final List<JournalEntry> journalEntries = this.glJournalEntryRepository
                         .findUnReversedManualJournalEntriesByTransactionId(transactionId);
+                final boolean touchesDenominationManagedCashAccount = journalEntries.stream()
+                        .anyMatch(je -> je.getGlAccount() != null && denominationManagedGlAccountIds.contains(je.getGlAccount().getId()));
+                if (touchesDenominationManagedCashAccount) {
+                    continue;
+                }
                 revertJournalEntry(journalEntries, "defining opening balance");
             }
 
@@ -865,6 +889,55 @@ public class JournalEntryWritePlatformServiceJpaRepositoryImpl implements Journa
         }
     }
 
+    /**
+     * The GL account(s) Financial Activity 101 (Cash at Vault) / 102 (Cash at Teller) map to. Shared
+     * by the validation below and by defineOpeningBalance's own revert step, so both agree on exactly
+     * which account(s) Migrate Cash Denomination owns.
+     */
+    private List<Long> resolveDenominationManagedCashGlAccountIds() {
+        final List<Long> ids = new ArrayList<>();
+        for (final FinancialActivityAccount mapping : this.financialActivityAccountRepositoryWrapper.findAll()) {
+            final Integer type = mapping.getFinancialActivityType();
+            if ((type != null && (type == 101 || type == 102)) && mapping.getGlAccount() != null) {
+                ids.add(mapping.getGlAccount().getId());
+            }
+        }
+        return ids;
+    }
+
+    /**
+     * The GL account(s) mapped to Financial Activity 101 (Cash at Vault) / 102 (Cash at Teller) are
+     * managed exclusively through Migrate Cash Denomination (BranchDayRegisterApiResource#migrateCashDenomination),
+     * which keeps the GL figure tied to an actual counted note-and-coin breakdown, and validates any
+     * redefinition against that same count. Defining or redefining that account's opening balance here
+     * instead - as a bare number, with no denomination breakdown behind it - would let the GL figure
+     * drift away from what is physically in the till, with nothing left to catch the mismatch. So this
+     * command refuses to touch either of those accounts at all, on either side of the entry, rather than
+     * only when the amount would differ from what is already posted: the physical count is the only
+     * source of truth for this account, never a number typed into a generic opening-balance grid.
+     */
+    private void validateNoDenominationManagedCashAccounts(final JournalEntryCommand command) {
+        final List<Long> denominationManagedGlAccountIds = resolveDenominationManagedCashGlAccountIds();
+        if (denominationManagedGlAccountIds.isEmpty()) {
+            return;
+        }
+        final List<SingleDebitOrCreditEntryCommand> allEntries = new ArrayList<>();
+        if (command.getDebits() != null) {
+            allEntries.addAll(Arrays.asList(command.getDebits()));
+        }
+        if (command.getCredits() != null) {
+            allEntries.addAll(Arrays.asList(command.getCredits()));
+        }
+        for (final SingleDebitOrCreditEntryCommand entry : allEntries) {
+            if (denominationManagedGlAccountIds.contains(entry.getGlAccountId())) {
+                throw new GeneralPlatformDomainRuleException("error.msg.journalentry.opening.balance.cash.account.locked",
+                        "This account is the tenant's Cash at Vault / Cash at Teller account and is managed through "
+                                + "Migrate Cash Denomination - it cannot be set or changed from Migrate Opening Balances.",
+                        entry.getGlAccountId());
+            }
+        }
+    }
+
     @Override
     public void createJournalEntriesForClientTransactions(Map<String, Object> accountingBridgeData) {
         final ClientTransactionDTO clientTransactionDTO = this.helper.populateClientTransactionDtoFromMap(accountingBridgeData);

fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/LedgerTransactionId.java

@@ -0,0 +1,157 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.accounting.journalentry.service;
+
+import java.sql.Date;
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import org.apache.fineract.infrastructure.core.service.DateUtils;
+import org.springframework.jdbc.core.JdbcTemplate;
+
+/**
+ * Mints the transaction id that ties the rows of one posting together in acc_gl_journal_entry.
+ *
+ * <p>
+ * Every feature here that posts a journal entry by direct JDBC used to invent this id by hand, and the two
+ * shapes that emerged were each wrong in their own way. Some concatenated a business row's own primary key
+ * ({@code "DIVROUND" + dividendPayOutId}); a primary key is only unique while its sequence keeps climbing,
+ * so a reset hands the same number out twice - which is exactly how two unrelated share withdrawals came to
+ * share one transaction id and render as a single doubled voucher. Others concatenated
+ * {@code System.nanoTime()}, which is unique but says nothing to whoever reads it off a screen
+ * ({@code "CASHMIG-1-20260913-923935527932300"}).
+ *
+ * <p>
+ * This generator replaces both with one readable shape, {@code PREFIX-YYMMDD-NNNN}:
+ *
+ * <pre>
+ *   SHWGL-260916-0001   the first share-withdrawal GL settlement posted on 16 Sep 2026
+ *   DIVRND-260916-0007  the seventh dividend rounding posted that day
+ * </pre>
+ *
+ * The prefix names the event, the date is the tenant's business date, and the serial restarts at 0001 each
+ * day. That makes a transaction id self-describing: a reader can tell what it was and when it happened
+ * without looking anything up.
+ *
+ * <p>
+ * Uniqueness does not depend on any business table. The serial comes from {@code m_ledger_txn_sequence}, a
+ * counter that belongs to no entity, so no entity's sequence can make it repeat. The counter is bumped by a
+ * single {@code INSERT ... ON CONFLICT DO UPDATE}, which takes and releases the row lock atomically, so two
+ * users posting at the same instant are serialised by the database rather than handed the same number - the
+ * same mechanism {@code m_voucher_sequence} already uses for voucher numbers.
+ *
+ * <p>
+ * The counter alone would still repeat if that table were ever truncated or rewound by hand, which is
+ * precisely the accident being defended against, so the minted id is also checked against the ledger before
+ * being handed back and the counter is advanced past anything already in use. That makes a duplicate
+ * impossible by construction rather than by convention: the id is only returned once no row holds it.
+ *
+ * <p>
+ * Ids already in the ledger keep their old shape. Nothing reconstructs a custom id to find its rows again
+ * (every call site mints one, posts with it, and never derives it a second time), so old and new shapes
+ * coexist without anything needing to read both.
+ *
+ * <p>
+ * Postings made by Fineract's own command path are not covered here and keep their native
+ * {@code "S"/"L"/"SH"/"C" + transaction id} form, which {@code AccountingProcessorHelper} derives and
+ * several readers reconstruct. Those readers are hardened at the query instead, by resolving to the most
+ * recently posted rows rather than assuming the text is unique.
+ */
+public final class LedgerTransactionId {
+
+    /** Guards against an impossible-in-practice runaway if the ledger and the counter disagree. */
+    private static final int MAX_PROBES = 50;
+
+    private static final DateTimeFormatter YYMMDD = DateTimeFormatter.ofPattern("yyMMdd");
+
+    private LedgerTransactionId() {}
+
+    /**
+     * Returns the next transaction id for this kind of posting, e.g. {@code SHWGL-260916-0001}.
+     *
+     * @param prefix
+     *            short uppercase code naming the event, from {@link LedgerTxnPrefix}
+     */
+    public static String next(final JdbcTemplate jdbcTemplate, final String prefix) {
+        // Tenant timezone, not the server's - the day the counter resets on has to be the branch's
+        // business day, otherwise a late-evening posting lands in the wrong series.
+        final LocalDate today = LocalDate.now(DateUtils.getDateTimeZoneOfTenant());
+        final String datePart = today.format(YYMMDD);
+
+        for (int probe = 0; probe < MAX_PROBES; probe++) {
+            final int serial = nextSerial(jdbcTemplate, prefix, today);
+            final String candidate = String.format("%s-%s-%04d", prefix, datePart, serial);
+            if (!isTaken(jdbcTemplate, candidate)) {
+                return candidate;
+            }
+            // Only reachable if the counter was rewound behind the ledger by hand. Bumping again walks
+            // it forward until it clears whatever is already posted, which self-heals the counter.
+        }
+        throw new IllegalStateException("Could not mint a free ledger transaction id for prefix " + prefix + " after " + MAX_PROBES
+                + " attempts. The m_ledger_txn_sequence counter for this prefix is far behind the entries already posted today.");
+    }
+
+    /**
+     * Returns the id for a posting that has to be reproducible, e.g. {@code SAVINT-260916-P0002}.
+     *
+     * <p>
+     * Some postings are not one-shot: a pooled interest run pays hundreds of members, and a run that
+     * stops halfway is resumed rather than restarted. Those resumed legs belong to the posting that
+     * started them, so the id has to come out the same on the second pass - a counter would hand the
+     * remainder a different id and split one posting across two transactions. This builds the id from
+     * what identifies the run instead: the same prefix, date and discriminator always produce the same
+     * string, and no counter is consumed.
+     *
+     * <p>
+     * Uniqueness rests on the caller's own discriminator being unique for that prefix and date (the
+     * product being posted, say), which is what makes the id reproducible in the first place. Use
+     * {@link #next} for everything else - a posting that happens once wants a counter, not a formula.
+     * The {@code P} marks the tail as a discriminator so it is not misread as a serial.
+     *
+     * @param date
+     *            the date the posting belongs to, which is not always today - interest can be posted
+     *            for an earlier day
+     * @param discriminator
+     *            what makes this run distinct from another on the same date, e.g. the product id
+     */
+    public static String forDatedSeries(final String prefix, final LocalDate date, final long discriminator) {
+        return String.format("%s-%s-P%04d", prefix, date.format(YYMMDD), discriminator);
+    }
+
+    /**
+     * Reserves the next counter value for one (prefix, day) series.
+     *
+     * The INSERT ... ON CONFLICT DO UPDATE both creates the series on its first use of the day and
+     * increments it thereafter. Being a single statement it is atomic, so no explicit lock is needed.
+     */
+    private static int nextSerial(final JdbcTemplate jdbcTemplate, final String prefix, final LocalDate day) {
+        return jdbcTemplate.queryForObject("""
+                INSERT INTO m_ledger_txn_sequence (prefix, series_date, last_number)
+                VALUES (?,?,1)
+                ON CONFLICT (prefix, series_date)
+                DO UPDATE SET last_number = m_ledger_txn_sequence.last_number + 1
+                RETURNING last_number
+                """, Integer.class, prefix, Date.valueOf(day));
+    }
+
+    private static boolean isTaken(final JdbcTemplate jdbcTemplate, final String transactionId) {
+        final Boolean taken = jdbcTemplate.queryForObject("SELECT EXISTS (SELECT 1 FROM acc_gl_journal_entry WHERE transaction_id = ?)",
+                Boolean.class, transactionId);
+        return Boolean.TRUE.equals(taken);
+    }
+}

fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/LedgerTxnPrefix.java

@@ -0,0 +1,87 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.accounting.journalentry.service;
+
+/**
+ * The event codes that open a transaction id minted by {@link LedgerTransactionId}.
+ *
+ * <p>
+ * They live together in one place so a reader can decode any transaction id on a screen from a single list,
+ * and so no two features can drift into naming the same event differently - which had already happened:
+ * dividend forfeiture was posting under {@code DIVFORF} from one service and {@code DIVFORFEIT} from
+ * another, for the same event.
+ *
+ * <p>
+ * Codes are uppercase, up to eight characters, and grouped by the module that raises them. A code is part of
+ * the audit trail once it has been posted, so treat these as append-only: add a new one for a new event
+ * rather than renaming an existing one, which would leave already-posted entries speaking a language nothing
+ * else uses any more.
+ */
+public final class LedgerTxnPrefix {
+
+    private LedgerTxnPrefix() {}
+
+    // A clerk's share withdrawal has no code here on purpose: it posts under the transaction id the
+    // native redeem command already minted ("SH" + share transaction id), because its debit leg is
+    // that command's own and the two have to group as one balanced entry.
+
+    // ── Share tranche funding ─────────────────────────────────────────────────
+    /** Additional share tranche: reversal of the stock reference posting. */
+    public static final String SHARE_TRANCHE_REFERENCE = "SHTREF";
+    /** Additional share tranche funded from the member's savings account. */
+    public static final String SHARE_TRANCHE_SAVINGS = "SHTSAV";
+
+    // ── Share collection and advances ─────────────────────────────────────────
+    /** Share application money collected. */
+    public static final String SHARE_COLLECTION = "SHCOL";
+    /** Share advance collected against a future allotment. */
+    public static final String SHARE_ADVANCE = "SHADV";
+    /** Share advance applied to an allotment. */
+    public static final String SHARE_ADVANCE_APPLIED = "SHAPP";
+
+    // ── Dividend ──────────────────────────────────────────────────────────────
+    /** Dividend claim paid out to a member. */
+    public static final String DIVIDEND_CLAIM = "DIVCLM";
+    /** Dividend declaration posted. */
+    public static final String DIVIDEND_DECLARED = "DIVDCL";
+    /** Dividend declaration approved. */
+    public static final String DIVIDEND_APPROVED = "DIVAPR";
+    /** Dividend payout closed off. */
+    public static final String DIVIDEND_CLOSED = "DIVCLS";
+    /** Rounding difference on a dividend payout. */
+    public static final String DIVIDEND_ROUNDING = "DIVRND";
+    /** Unclaimed dividend forfeited. */
+    public static final String DIVIDEND_FORFEIT = "DIVFRF";
+
+    // ── Branch day and cash ───────────────────────────────────────────────────
+    /** Opening cash migrated into the branch day register. */
+    public static final String CASH_MIGRATION = "CSHMIG";
+    /** Rounding difference on a clerk's day closure. */
+    public static final String CLOSURE_ROUNDING = "CLSRND";
+
+    // ── Year end ──────────────────────────────────────────────────────────────
+    /** Year-end transfer of income into the profit account. */
+    public static final String YEAR_END_PROFIT = "YEPFT";
+    /** Year-end closure of an income or expense account. */
+    public static final String YEAR_END_CLOSE = "YECLS";
+
+    // ── Savings ───────────────────────────────────────────────────────────────
+    /** Pooled savings interest posting for one product and date. */
+    public static final String SAVINGS_INTEREST_POOLED = "SAVINT";
+}

fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/ShareAccountingSuppression.java

@@ -0,0 +1,83 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.fineract.accounting.journalentry.service;
+
+import java.util.function.Supplier;
+
+/**
+ * Lets a register that posts a share transaction's accounting itself tell the platform not to post its
+ * own.
+ *
+ * <h3>Why this exists</h3>
+ *
+ * <p>
+ * Fineract books every share transaction against a fixed "Shares Reference" account taken from the
+ * product's GL mapping: a redemption posts Dr Shares Equity / Cr Shares Reference, whatever the money
+ * actually did. That account is a placeholder for a counterparty the platform does not know, and in a
+ * real core banking ledger there is no such thing — a redemption paid in cash credits the cash
+ * account, and one settled by transfer credits the account it was transferred to. Naming a single
+ * asset account for both leaves every redemption sitting against a GL the money never touched, which
+ * then has to be corrected by hand.
+ *
+ * <p>
+ * The governed clerk registers already know the real counterparty, because the clerk keyed it: the
+ * linked savings account, or the GL picked on the transfer's credit row. They post the redemption
+ * themselves, correctly, in one balanced entry. Before this flag existed they had to let the platform
+ * post its version first and then reverse the half that was wrong, which left a dead Cr Shares
+ * Reference row behind on every redemption and made the ledger read as though cash had moved.
+ *
+ * <h3>Why a flag and not the product's accounting rule</h3>
+ *
+ * <p>
+ * Turning the share product's accounting off entirely ({@code m_share_product.accounting_type = NONE})
+ * would silence the platform everywhere, including the share account screen's own Redeem action, which
+ * no register covers — those redemptions would post nothing at all and go unnoticed, because that
+ * branch fails silently by design. Scoping the suppression to the one call that is about to post its
+ * own entry leaves every other path exactly as it is.
+ *
+ * <p>
+ * A ThreadLocal rather than a request attribute, and restoring the previous value rather than clearing
+ * it, for the same reasons as {@code VoucherService.withOwnVoucher} — a batch job has no request to
+ * hang the flag on, and nesting must not switch the suppression off early for an outer caller.
+ */
+public final class ShareAccountingSuppression {
+
+    private static final ThreadLocal<Boolean> CALLER_POSTS_SHARE_ENTRIES = ThreadLocal.withInitial(() -> Boolean.FALSE);
+
+    private ShareAccountingSuppression() {}
+
+    /**
+     * Runs {@code command} with the platform's own share journal entries suppressed, for a caller that
+     * posts the transaction's accounting itself.
+     */
+    public static <T> T withOwnShareEntries(final Supplier<T> command) {
+        final boolean previous = CALLER_POSTS_SHARE_ENTRIES.get();
+        CALLER_POSTS_SHARE_ENTRIES.set(Boolean.TRUE);
+        try {
+            return command.get();
+        } finally {
+            CALLER_POSTS_SHARE_ENTRIES.set(previous);
+        }
+    }
+
+    /** False only while a caller inside {@link #withOwnShareEntries} is posting its own entries. */
+    public static boolean shouldPostShareEntries() {
+        return !CALLER_POSTS_SHARE_ENTRIES.get();
+    }
+}