@classytic/ledger-bd 0.3.1 → 0.5.1

package/CHANGELOG.md

@@ -3,6 +3,198 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-06
+
+Seven opt-in vertical extensions plus an NBR canonical reporting-code
+layer — the "become a standard for BD accountants" pass. Research-grounded
+(4-5 Jul 2026 web research across NBR/BMDC/DGHS/MRA/NGOAB/Bangladesh Bank
+sources), with confidence flags per account — see each vertical's README.
+
+### Added — vertical extensions (`src/verticals/`, subpath `./verticals`)
+
+New, opt-in, additive-only (core chart files untouched); apply with
+`applyVerticals(BD_ACCOUNT_TYPES, [...names])`:
+
+- **`school`** (10 accounts) — development/session/hostel/transport fee
+  revenue, board-exam pass-through liability, two statutory teacher-fund
+  payables (Retirement Benefit Board + Welfare Trust — genuinely distinct
+  bodies), scholarship-waiver contra-revenue. Deliberately does NOT model
+  MPO as a ledger account — since the Jan 2025 EFT rollout the government
+  salary portion never touches the institution's own bank account.
+- **`agro`** (12 accounts) — crop/jute/aquaculture WIP and inventory stages,
+  cold-storage receivable + sourced ~3.82% spoilage allowance, pledged-
+  produce financing under the Secured Transactions (Movable Property) Act
+  2023 (NOT "warehouse receipt financing" — no such standalone BB scheme
+  could be confirmed), direct-cash agro-subsidy income.
+- **`real-estate`** (4 accounts) — contract asset/unbilled revenue distinct
+  from retention receivable, landowner joint-venture unit-share payable,
+  contractor mobilization-advance-received, guarantee margin deposit. Flags
+  as explicitly open: no actual BD-listed developer's revenue-recognition
+  policy could be located.
+- **`ngo-microfinance`** (13 accounts) — loan portfolio by product,
+  interest-in-suspense, PKSF per-tranche borrowing/fees (mirrors PKSF's own
+  audited "Schedule of Service Charge Receivables"), member savings
+  (compulsory/voluntary), NGOAB-mandated project-restricted bank account
+  and fund.
+- **`restaurant`** (6 accounts) — service-charge payable/revenue (no BD
+  Labour Act mandate for staff distribution could be verified — modeled as
+  a policy choice, not compliance), cross-border franchise royalty payable
+  (20% WHT), aggregator-commission contra-revenue (confirmed net-settlement
+  via actual foodpanda invoice samples), beverage inventory.
+- **`rmg-enhancement`** (5 accounts) — corrects two misconceptions from an
+  earlier draft: FDBP is bank bill-discounting/financing, NOT a "~0.6%
+  incentive"; UD (Utilization Declaration) is a compliance filing with no
+  cash event, NOT a subsidy trigger. Adds the genuine gap — a cash-incentive
+  receivable for the real, sourced 180-day+ realization-to-disbursement lag.
+- **`hospital-enhancement`** (3 accounts) — consultant/doctor fee payable
+  (legitimate collect-and-remit model) and patient admission deposit.
+  Deliberately does NOT ship a "diagnostic referral commission" account —
+  real and material (20-50% of test cost, well-documented) but explicitly
+  prohibited under BMDC's Code of Professional Conduct §4.3.1; building
+  dedicated tooling for it would mean designing software to facilitate a
+  documented ethics violation.
+
+### Added — NBR canonical schedule (`src/reporting/nbr-schedule/`, subpath `./reporting/nbr-schedule`)
+
+A fixed numeric reporting taxonomy — confirmed via research that no such
+crosswalk exists anywhere in Bangladesh's legal lineage (Companies Act 1994
+Schedule XI, like India's Schedule III and the UK's Schedule 4, uses
+positional letter/Roman/Arabic outline labels, never a persistent numeric
+code — the same role Canada's GIFI plays there has no BD equivalent to
+adopt). Built against the closest real analog: NBR's IT-11GHA company tax
+return, whose Part IV carries a fixed, currently-filed, numbered Balance
+Sheet/P&L box schema (47-67) — hence the name.
+
+- `resolveScheduleBox(account)` — classifies ANY `AccountType`, core chart
+  or vertical extension, onto a box. Covers the entire chart, not just new
+  accounts, per explicit design requirement.
+- `buildNbrScheduleReport(trialBalance, accountTypes)` — aggregates a trial
+  balance into the schedule.
+- `getUnmappedAccounts(accountTypes)` — coverage audit; the test suite
+  asserts zero unmapped accounts (excluding tax expense, which is computed
+  after Box 60 and has no box among 47-59) across the core chart AND all
+  seven verticals combined.
+- Explicitly flagged as this package's own interpretive judgment, not a
+  government-published crosswalk — see `src/reporting/nbr-schedule/README.md`
+  for what's gazette/circular-verified vs. inferred.
+
+### Fixed — mapping refinements found via a full-chart audit
+
+The initial mapping passed all narrow spot-check tests, but dumping the
+resolved box for all 757 accounts and reviewing it end-to-end (not just the
+handful of codes the first test pass happened to touch) surfaced 4 real
+misclassifications, now fixed and covered by dedicated regression tests:
+
+- Bonds/Debentures/Sukuk (2322/2323) were falling into the generic 65B
+  "long-term borrowings" bucket; the schedule has a dedicated 65A "Bonds/
+  Debentures" box that nothing was ever routed to.
+- Current Portion of Long-Term Debt (2200) landed in 66D "other" instead of
+  66A "short-term borrowings" — it's literally the current-year slice of
+  actual borrowings.
+- L/C Margin Liability (2205) was swept into 66C "provisions" alongside
+  warranty/returns/legal-claims accruals, but it's a real bank-held deposit,
+  not an estimate.
+- A blanket rule routing every account tagged `parentCode: 'Other Expenses'`
+  into box 57 (Financial expenses) incorrectly caught 7 non-financial
+  one-off losses (loss on sale of assets, penalties, demurrage, theft,
+  natural disaster, crop loss — 6810-6817) that share that parentCode with
+  genuine interest/FX-cost accounts in the core chart, but belong in 55
+  (Other operating expenses). Replaced with pure numeric-range classification
+  for the whole Income Statement-Expense category.
+
+### Tests
+
+68 passing (43 existing + 25 new: 6 vertical code-collision/composition
+tests, 19 NBR canonical schedule mapping/coverage/report tests, including
+4 regression tests for the audit findings above).
+
+## [0.4.0] - 2026-07-02
+
+Tax-layer sync with `@classytic/bd-tax` 0.3.0 — the code table, the Mushak
+9.1 template, and the chart now cover the same law the calculator does.
+
+### Added — tax codes
+
+- **Trading-stage VAT codes**: `BD-VAT-4.5`, `BD-VAT-2.4`, `BD-VAT-2`,
+  `BD-VAT-1.5` (no input credit; report on the new template lines 20–23).
+- **`BD-TOT-FIXED`** — the FY2026-27 fixed-amount turnover-tax model
+  (rate 0; post the assessed amount). `BD-TOT-4` stays for historical
+  postings, renamed "(historical)".
+- **`BD-AT-IMP`** — advance VAT at customs (7.5% commercial / 2%
+  manufacturer), `recoverable`, reporting on line 24.
+- **VDS codes** (`BD-VDS-15/10/7.5/5/2`) — percent of service value per
+  the VDS Rules 2025 service table, all reporting on line 25.
+- **New TDS codes**: `BD-TDS-PROF-IND` (15%), `BD-TDS-INT-IND` (10%),
+  `BD-TDS-DIV-IND` (10%), `BD-TDS-TECH` (10%), `BD-TDS-TRANSPORT` (2%,
+  FY2026-27), `BD-TDS-EXP` (1%, s.123).
+
+### Fixed — TDS code rates (Income Tax Act 2023)
+
+The table still carried ITO-1984-era rates that contradicted bd-tax's
+matrix: `BD-TDS-PROF` 10% → **7.5%** (entities; s.90), `BD-TDS-RENT`
+5% → **10%** (s.109), `BD-TDS-INT` 10% → **20%** (companies; s.102),
+`BD-TDS-DIV` 10% → **20%** (companies; s.117), `BD-TDS-ADV` 4% → **3%**.
+2135 TDS sub-account rates/descriptions updated to match, plus new
+`2135.TDS.TECH` and `2135.TDS.TRANSPORT` accounts.
+
+### Added — receivable-side tax accounts (`TAX_RECEIVABLE_ACCOUNTS`)
+
+`1151.AIT.IMPORT`, `1151.AIT.OTHER`, `1152.TDS.SUFFERED`,
+`1153.VDS.SUFFERED`, `1153.AT.IMPORT` — the withholding-SUFFERED side.
+Matters from 1 Jul 2026: the Finance Act 2026 withdrew minimum-tax
+treatment, so TDS/AIT suffered is a true adjustable asset, not an expense.
+
+### Changed — Mushak 9.1 template
+
+Lines **20–23** (trading-stage outputs, summed into line 9), **24** (AT
+credit on imports) and **25** (VDS increasing adjustment) appended; line
+17 now computes `12 + 13 + 16 + 25 − 24`. Existing line numbers are
+untouched and the old math is preserved when the new lines are absent.
+Line 6 re-described for the fixed TOT model.
+
+### Gazette verification (3 Jul 2026)
+
+`BD-TDS-ADV` corrected 3% → **5%** (ITA 2023 s.92 — media advertising
+bills; media buying agents route via `BD-TDS-COMM`), with the matching
+`2135.TDS.ADV` account update. All other 0.4.0 rates confirmed against
+the verification pass (see `@classytic/bd-tax`
+`research/FY2026-27/06-gazette-verification.md`).
+
+### Build
+
+- tsdown → **^0.22.3**, aligned with `@classytic/arc`'s pattern:
+  `skipNodeModulesBundle: true` + `neverBundle: [/^@classytic\//]`
+  (a bundled second `@classytic/ledger` copy would break
+  `defineCountryPack` identity), explicit `target: node22`.
+- Peer unchanged and verified: `@classytic/ledger >= 0.12.0` is the sole
+  runtime import (`defineCountryPack`); everything else is type-only.
+
+### Peers / dev stack (pre-publish refresh)
+
+- Peer: `@classytic/ledger >= 0.15.0` (was >= 0.12.0) — validated against
+  the PUBLISHED 0.15.0 (43/43 on a clean registry install). Dev stack
+  refreshed to published lines: ledger ^0.15.0, repo-core ^0.7.0,
+  primitives ^0.9.1, mongokit ^3.17.0 (resolves 3.18).
+
+### Tests
+
+43 passing (15 existing + 28 new code/template/account pins).
+
+## [0.3.2] - 2026-07-02
+
+### Added
+
+Four VAT-collected tax sub-accounts under 2132 matching `@classytic/bd-tax`
+0.2.0's new Third-Schedule trading-stage rate codes:
+
+- `2132.VAT4.5.COLLECTED` — real estate >1,600 sqft
+- `2132.VAT2.4.COLLECTED` — medicine trading stage (pharmacies)
+- `2132.VAT2.COLLECTED` — petroleum trading / real estate ≤1,600 sqft
+- `2132.VAT1.5.COLLECTED` — wholesale trading stage
+
+`2132.TOT4.COLLECTED` description updated for the FY2026-27 fixed-amount
+turnover-tax model (post assessed fixed amounts to the same head).
+
 ## [0.2.3]
 
 ### Added

package/README.md

@@ -104,6 +104,36 @@ All 8 Bangladesh divisions with tax-code mappings:
 import { DIVISIONS, ALL_DIVISIONS } from '@classytic/ledger-bd';
 ```
 
+### Vertical Extensions (opt-in industry overlays)
+
+The core chart above is a comprehensive commerce/ecommerce/light-manufacturing
+(RMG) chart. Seven opt-in vertical overlays add industry-specific accounts on
+top — school/education, agro/agriculture, real estate/construction, NGO/
+microfinance, restaurant/hospitality, plus RMG and hospital enhancements. Not
+seeded by default; see [`src/verticals/README.md`](src/verticals/README.md).
+
+```typescript
+import { BD_ACCOUNT_TYPES } from '@classytic/ledger-bd';
+import { applyVerticals } from '@classytic/ledger-bd/verticals';
+
+const schoolChart = applyVerticals(BD_ACCOUNT_TYPES, ['school']);
+```
+
+### NBR Canonical Schedule (canonical reporting-code layer)
+
+A fixed numeric taxonomy that maps ANY chart of accounts — core or with
+verticals applied — onto Bangladesh's closest real analog for this kind of
+crosswalk: NBR's IT-11GHA company tax-return schedule (boxes 47-67). See
+[`src/reporting/nbr-schedule/README.md`](src/reporting/nbr-schedule/README.md)
+for what's verified vs. this package's own interpretive judgment.
+
+```typescript
+import { BD_ACCOUNT_TYPES } from '@classytic/ledger-bd';
+import { buildNbrScheduleReport } from '@classytic/ledger-bd/reporting/nbr-schedule';
+
+const report = buildNbrScheduleReport(trialBalanceRows, BD_ACCOUNT_TYPES);
+```
+
 ## Documentation
 
 See the [@classytic/ledger](https://github.com/classytic/fajr/tree/main/packages/ledger) package for full engine documentation.

package/dist/index.d.mts

@@ -1,5 +1,4 @@
-import * as _$_classytic_ledger0 from "@classytic/ledger";
-import { AccountType } from "@classytic/ledger";
+import { AccountResolverConfig, AccountType } from "@classytic/ledger";
 
 //#region src/accounts/assets.d.ts
 declare const CURRENT_ASSETS: AccountType[];
@@ -47,6 +46,7 @@ declare const VAT_LIABILITY_ACCOUNTS: AccountType[];
 declare const VAT_ASSET_ACCOUNTS: AccountType[];
 declare const TDS_LIABILITY_ACCOUNTS: AccountType[];
 declare const VDS_LIABILITY_ACCOUNTS: AccountType[];
+declare const TAX_RECEIVABLE_ACCOUNTS: AccountType[];
 declare const ALL_TAX_ACCOUNTS: AccountType[];
 //#endregion
 //#region src/accounts/codes.d.ts
@@ -102,7 +102,9 @@ declare const BD_ACCOUNT_CODES: {
    */
   readonly INTER_BRANCH_RECEIVABLE: "1145";
   readonly VAT_RECEIVABLE: "1150";
-  readonly ADVANCE_INCOME_TAX: "1151";
+  readonly ADVANCE_INCOME_TAX: "1151"; /** 1152 — TDS Receivable. Income tax deducted at source by our customers/payers. */
+  readonly TDS_RECEIVABLE: "1152"; /** 1200 — Advance Tax / VAT paid to government (offsettable at filing). */
+  readonly ADVANCE_TAX_PAID: "1200";
   /**
    * 1153 — VDS Receivable. The portion of output VAT withheld by a
    * designated buyer (govt entity / large corporate) and deposited to
@@ -174,7 +176,8 @@ declare const BD_ACCOUNT_CODES: {
    */
   readonly CUSTOMER_ADVANCE: "2191";
   readonly INCOME_TAX_PAYABLE: "2131";
-  readonly VAT_OUTPUT_PAYABLE: "2132";
+  readonly VAT_OUTPUT_PAYABLE: "2132"; /** 2133 — Supplementary Duty (SD) Payable on specified goods/services. */
+  readonly SD_OUTPUT_PAYABLE: "2133";
   readonly TDS_PAYABLE: "2135";
   /**
    * 2136 — VDS Payable. Amount we must remit to NBR when we withhold VDS
@@ -182,7 +185,9 @@ declare const BD_ACCOUNT_CODES: {
    * Distinct from 2135 (TDS) — VDS is VAT-side withholding, TDS is income-tax-side.
    */
   readonly VDS_PAYABLE: "2136";
-  readonly SALES_REVENUE: "4111";
+  readonly SALES_REVENUE: "4111"; /** 4114 — Sales Returns & Allowances. Contra-revenue for customer returns. */
+  readonly SALES_RETURNS: "4114"; /** 4115 — Sales Discount. Contra-revenue for cash / settlement discounts given. */
+  readonly SALES_DISCOUNT: "4115";
   /**
    * 4147 — Transport / Freight Revenue. When delivery is sold as a
    * line-item (Tk 60 delivery charge on the invoice) instead of being
@@ -226,7 +231,8 @@ declare const BD_ACCOUNT_CODES: {
    * on a Loss account and inflates profit.
    */
   readonly INVENTORY_GAIN: "4317"; /** 5111 — Cost of Goods Sold — Raw Materials */
-  readonly COGS_MATERIALS: "5111";
+  readonly COGS_MATERIALS: "5111"; /** 5503 — Purchase Returns & Allowances. Contra-COGS for returns to vendors. */
+  readonly PURCHASE_RETURNS: "5503";
   /**
    * 5116 — Import Cost (duty + freight + insurance). Capitalized to
    * inventory at landed cost. Use this when a CIF/FOB import flow needs
@@ -365,6 +371,9 @@ declare const BD_ACCOUNT_CODES: {
 type BDAccountCode = (typeof BD_ACCOUNT_CODES)[keyof typeof BD_ACCOUNT_CODES];
 type BDAccountKey = keyof typeof BD_ACCOUNT_CODES;
 //#endregion
+//#region src/accounts/account-rules.d.ts
+declare const BD_ACCOUNT_RULES: AccountResolverConfig;
+//#endregion
 //#region src/accounts/index.d.ts
 /** Complete flat array of all BD account types + tax sub-accounts + group labels */
 declare const BD_ACCOUNT_TYPES: readonly AccountType[];
@@ -490,6 +499,6 @@ declare const ALL_DIVISIONS: ("Dhaka" | "Chittagong" | "Rajshahi" | "Khulna" | "
  *
  * @module @classytic/ledger-bd
  */
-declare const bangladeshPack: _$_classytic_ledger0.CountryPack;
+declare const bangladeshPack: import("@classytic/ledger").CountryPack;
 //#endregion
-export { ADMIN_EXPENSES, ALL_DIVISIONS, ALL_TAX_ACCOUNTS, ASSETS, BANKING_REVENUE, type BDAccountCode, type BDAccountKey, BD_ACCOUNT_CODES, BD_ACCOUNT_TYPES, BD_DIVISIONS, COGS, COST_OF_SERVICES, CURRENT_ASSETS, CURRENT_LIABILITIES, DEPRECIATION, DIRECT_LABOR, DIRECT_MATERIALS, DIVISIONS, EMPLOYEE_COSTS, EQUITY, EXPENSES, FINANCIAL_EXPENSES, INDUSTRY_REVENUE, LIABILITIES, MANUFACTURING_OVERHEAD, NGO_REVENUE, NON_CURRENT_ASSETS, NON_CURRENT_LIABILITIES, OTHER_INCOME, OTHER_OPERATING, PREMISES_COSTS, PROVISIONS, PURCHASES, REVENUE, SALES_REVENUE, SELLING_DISTRIBUTION, ALL_TAX_CODES as TAX_CODES, TAX_CODES_BY_DIVISION, TAX_EXPENSE, TDS_LIABILITY_ACCOUNTS, VAT_ASSET_ACCOUNTS, VAT_LIABILITY_ACCOUNTS, VDS_LIABILITY_ACCOUNTS, bangladeshPack, getTaxCodeDetails, mushakReturnTemplate };
+export { ADMIN_EXPENSES, ALL_DIVISIONS, ALL_TAX_ACCOUNTS, ASSETS, BANKING_REVENUE, type BDAccountCode, type BDAccountKey, BD_ACCOUNT_CODES, BD_ACCOUNT_RULES, BD_ACCOUNT_TYPES, BD_DIVISIONS, COGS, COST_OF_SERVICES, CURRENT_ASSETS, CURRENT_LIABILITIES, DEPRECIATION, DIRECT_LABOR, DIRECT_MATERIALS, DIVISIONS, EMPLOYEE_COSTS, EQUITY, EXPENSES, FINANCIAL_EXPENSES, INDUSTRY_REVENUE, LIABILITIES, MANUFACTURING_OVERHEAD, NGO_REVENUE, NON_CURRENT_ASSETS, NON_CURRENT_LIABILITIES, OTHER_INCOME, OTHER_OPERATING, PREMISES_COSTS, PROVISIONS, PURCHASES, REVENUE, SALES_REVENUE, SELLING_DISTRIBUTION, ALL_TAX_CODES as TAX_CODES, TAX_CODES_BY_DIVISION, TAX_EXPENSE, TAX_RECEIVABLE_ACCOUNTS, TDS_LIABILITY_ACCOUNTS, VAT_ASSET_ACCOUNTS, VAT_LIABILITY_ACCOUNTS, VDS_LIABILITY_ACCOUNTS, bangladeshPack, getTaxCodeDetails, mushakReturnTemplate };