@mudraforge/statutory 2.11.0 → 2.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/CHANGELOG.md +155 -1
  2. package/CONTRIBUTING.md +2 -2
  3. package/README.md +1 -1
  4. package/SECURITY.md +2 -2
  5. package/SKILL.md +1 -1
  6. package/bin/cli.js +288 -27
  7. package/docs/ACCOUNTING_ASSURANCE_AUDIT_DOSSIER.md +276 -0
  8. package/docs/ARCHITECTURE.md +6 -6
  9. package/docs/CASE_01_FORM_TEXT.txt +48 -0
  10. package/docs/CATALOG.md +405 -39
  11. package/docs/CA_PILOT_BENCHMARK_CASES.md +282 -0
  12. package/docs/CORPUS_QUALITY.md +31 -22
  13. package/docs/DOMAIN_BREADTH_AND_DEPTH_COMPARISON.md +1 -1
  14. package/okf/corporate_ma_restructuring/business_combinations_indas_103/circulars/mca_notification_indas_103_business_combinations.md +41 -0
  15. package/okf/corporate_ma_restructuring/business_combinations_indas_103/forms/purchase_price_allocation_schedule.json +110 -0
  16. package/okf/corporate_ma_restructuring/business_combinations_indas_103/section.json +65 -0
  17. package/okf/corporate_ma_restructuring/impairment_of_assets_indas_36/circulars/mca_notification_indas_36_impairment.md +45 -0
  18. package/okf/corporate_ma_restructuring/impairment_of_assets_indas_36/forms/cgu_impairment_testing_register.json +53 -0
  19. package/okf/corporate_ma_restructuring/impairment_of_assets_indas_36/section.json +61 -0
  20. package/okf/corporate_ma_restructuring/share_based_payments_indas_102/circulars/icai_guidance_share_based_payments.md +37 -0
  21. package/okf/corporate_ma_restructuring/share_based_payments_indas_102/forms/esop_graded_vesting_amortization_schedule.json +49 -0
  22. package/okf/corporate_ma_restructuring/share_based_payments_indas_102/section.json +60 -0
  23. package/okf/direct_tax/income_taxes_deferred_tax_indas_12/circulars/mca_notification_indas_12_income_taxes.md +40 -0
  24. package/okf/direct_tax/income_taxes_deferred_tax_indas_12/forms/deferred_tax_asset_liability_reconciliation_schedule.json +46 -0
  25. package/okf/direct_tax/income_taxes_deferred_tax_indas_12/section.json +61 -0
  26. package/okf/direct_tax/tds_commission_194h/section.json +5 -4
  27. package/okf/direct_tax/tds_contractor_194c/section.json +3 -3
  28. package/okf/direct_tax/tds_ecommerce_194o/section.json +3 -3
  29. package/okf/direct_tax/tds_goods_194q/circulars/cbdt_circular_13_2021_guidelines.md +2 -2
  30. package/okf/direct_tax/tds_goods_194q/section.json +9 -3
  31. package/okf/direct_tax/tds_goods_393/section.json +6 -4
  32. package/okf/direct_tax/tds_individual_contract_194m/section.json +3 -3
  33. package/okf/direct_tax/tds_interest_194a/section.json +7 -4
  34. package/okf/direct_tax/tds_perquisites_194r/section.json +1 -1
  35. package/okf/direct_tax/tds_property_194ia/section.json +3 -3
  36. package/okf/direct_tax/tds_rent_194i/section.json +5 -4
  37. package/okf/direct_tax/tds_rent_individual_194ib/section.json +2 -2
  38. package/okf/direct_tax/tds_services_194j/circulars/cbdt_circular_03_2020_fts_rate_cut.md +1 -1
  39. package/okf/direct_tax/tds_services_194j/section.json +10 -3
  40. package/okf/indirect_tax_gst/common_itc_reversal_rule42_43/circulars/cbic_circular_170_2022_itc_reporting.md +30 -0
  41. package/okf/indirect_tax_gst/common_itc_reversal_rule42_43/circulars/cbic_notification_18_2022_cutoff_amendment.md +26 -0
  42. package/okf/indirect_tax_gst/common_itc_reversal_rule42_43/forms/gstr_3b_table_4b1_reversal_schedule.json +101 -0
  43. package/okf/indirect_tax_gst/common_itc_reversal_rule42_43/forms/rule_42_43_annual_reconciliation_worksheet.json +87 -0
  44. package/okf/indirect_tax_gst/common_itc_reversal_rule42_43/section.json +65 -0
  45. package/okf/indirect_tax_gst/itc_reversal_rule37_37a/circulars/cbic_circular_192_2023_ecl_interest_calculation.md +36 -0
  46. package/okf/indirect_tax_gst/itc_reversal_rule37_37a/section.json +8 -1
  47. package/okf/indirect_tax_gst/rcm_liability_sec9_3/circulars/cbic_notification_07_2025_composition_rent_exclusion.md +41 -0
  48. package/okf/indirect_tax_gst/rcm_liability_sec9_3/circulars/cbic_notification_09_2024_renting_rcm.md +37 -0
  49. package/okf/indirect_tax_gst/rcm_liability_sec9_3/circulars/gst_council_55th_meeting_renting_rcm_regularization.md +31 -0
  50. package/okf/indirect_tax_gst/rcm_liability_sec9_3/section.json +24 -2
  51. package/okf/international_tax/financial_instruments_ecl_indas_109/circulars/mca_notification_indas_109_financial_instruments.md +43 -0
  52. package/okf/international_tax/financial_instruments_ecl_indas_109/forms/indas_109_ecl_provision_matrix_schedule.json +43 -0
  53. package/okf/international_tax/financial_instruments_ecl_indas_109/section.json +62 -0
  54. package/okf/manifest.json +71 -20
  55. package/okf/msme_commercial/lease_accounting_indas_116/circulars/mca_notification_indas_116_leases.md +48 -0
  56. package/okf/msme_commercial/lease_accounting_indas_116/forms/lease_rou_asset_and_liability_schedule.json +55 -0
  57. package/okf/msme_commercial/lease_accounting_indas_116/section.json +67 -0
  58. package/okf/msme_commercial/provisions_contingencies_indas_37/circulars/mca_notification_indas_37_provisions.md +36 -0
  59. package/okf/msme_commercial/provisions_contingencies_indas_37/forms/provisions_and_contingent_liabilities_register.json +38 -0
  60. package/okf/msme_commercial/provisions_contingencies_indas_37/section.json +61 -0
  61. package/okf/msme_commercial/revenue_recognition_indas_115/circulars/mca_notification_indas_115_revenue_contracts.md +56 -0
  62. package/okf/msme_commercial/revenue_recognition_indas_115/forms/revenue_contract_5step_allocation_schedule.json +54 -0
  63. package/okf/msme_commercial/revenue_recognition_indas_115/section.json +69 -0
  64. package/package.json +7 -1
  65. package/src/calculators.js +2195 -260
  66. package/src/constants.js +1 -1
  67. package/src/index.js +407 -23
  68. package/src/tally.js +812 -0
  69. package/src/zoho_gstr2b.js +2964 -0
  70. package/types/index.d.ts +476 -0
package/types/index.d.ts CHANGED
@@ -199,6 +199,15 @@ export declare class StatutoryClient {
199
199
  calculateTransferPricingAlp(payload?: any): any;
200
200
  evaluateSection79LossContinuity(payload?: any): any;
201
201
  revalueForeignExchangeIndAs109(payload?: any): any;
202
+ calculateBusinessCombinationsIndAs103(payload?: any): any;
203
+ calculateImpairmentIndAs36(payload?: any): any;
204
+ calculateRevenueAllocationIndAs115(payload?: any): any;
205
+ calculateLeaseAmortizationIndAs116(payload?: any): any;
206
+ calculateExpectedCreditLossIndAs109(payload?: any): any;
207
+ calculateEsopAmortizationIndAs102(payload?: any): any;
208
+ calculateDeferredTaxIndAs12(payload?: any): any;
209
+ evaluateProvisionsAndContingenciesIndAs37(payload?: any): any;
210
+ calculateForeignCurrencyIndAs21(payload?: any): any;
202
211
  evaluateSection194A(payload?: any): any;
203
212
  evaluateSection194O(payload?: any): any;
204
213
  evaluateSection194IA(payload?: any): any;
@@ -209,6 +218,47 @@ export declare class StatutoryClient {
209
218
  evaluateSection281(payload?: any): any;
210
219
  calculateItcReversalRule37(payload?: any): any;
211
220
  calculateRule37ASupplierNonFilingReversal(payload?: any): any;
221
+ calculateRule42InputServiceReversal(payload?: any): any;
222
+ reconcileRule42AnnualTrueUp(payload?: any): any;
223
+ calculateRule43CapitalGoodsReversal(payload?: any): any;
224
+ calculateGstItcApportionmentRule42_43(payload?: any): any;
225
+ parseTallyDaybookCsv(csvText: string): DaybookVoucherInput[];
226
+ parseTallyDaybookXml(xmlText: string): DaybookVoucherInput[];
227
+ reconcileDaybook(vouchers: DaybookVoucherInput[], options?: ReconcileDaybookOptions): ReconcileDaybookResult;
228
+ reconcile194QDaybook(vouchers: DaybookVoucherInput[], options?: ReconcileDaybookOptions): ReconcileDaybookResult;
229
+ generateTallyJournalXml(reconciliationResult: ReconcileDaybookResult, options?: any): string;
230
+ generateTally194QJournalXml(reconciliationResult: ReconcileDaybookResult, options?: any): string;
231
+ generateAuditReport(reconciliationResult: ReconcileDaybookResult): string;
232
+ generateAuditMarkdownReport(reconciliationResult: ReconcileDaybookResult): string;
233
+ parseZohoBillsCsv(csvText: string): ZohoBillRecord[];
234
+ parseZohoBillsJson(jsonData: any): ZohoBillRecord[];
235
+ parseGstr2bJson(gstr2bData: any): Gstr2bRecord[];
236
+ reconcileZohoGstr2b(params: ReconcileZohoGstr2bParams): ReconcileZohoGstr2bResult;
237
+ generateGstr2bAuditMarkdownReport(reconResult: ReconcileZohoGstr2bResult): string;
238
+ generateGstr2bAuditReport(reconResult: ReconcileZohoGstr2bResult): string;
239
+ calculateOverdueStartDate(billDateIso: string): string | null;
240
+ calculateEclUtilizationInterest(params: {
241
+ unreversedItcInr: number | string;
242
+ overdueStartDate: string;
243
+ asOfDate: string;
244
+ reversalDate?: string | null;
245
+ eclLedgerHistory?: Array<{ date: string; balanceInr: number }>;
246
+ annualInterestRate?: number;
247
+ }): EclUtilizationAuditResult;
248
+ calculatePortfolioEclUtilizationInterest(params: {
249
+ overdueBills: Array<any>;
250
+ eclLedgerHistory: Array<{ date: string; balanceInr: number }>;
251
+ asOfDate?: string;
252
+ annualInterestRate?: number;
253
+ }): any;
254
+ buildEvidenceProvenance(params: any): EvidenceProvenance;
255
+ runWatchtower(options?: { okfDir?: string; verbose?: boolean }): Promise<WatchtowerReport>;
256
+ normalizeInvoiceNumber(raw: string): { exactKey: string; alphaNumericKey: string };
257
+ normalizeGstin(raw: string): { gstin: string | null; pan: string | null; stateCode: string | null; isValid: boolean };
258
+ cleanNumericAmount(val: any, options?: CleanNumericAmountOptions): number;
259
+ roundToPaisa(amount: number | string): number;
260
+ toIntegerPaise(amount: number | string, options?: string | ToIntegerPaiseOptions): number;
261
+ fromIntegerPaise(paise: number): number;
212
262
  getOutcomes(provision?: string, options?: StatutoryOutcomesOptions): Promise<StatutoryOutcomesResult>;
213
263
  explain(codeOrQuery: string, options?: any): any;
214
264
  }
@@ -336,14 +386,54 @@ export declare function decodeTaxIdentifier(rawId: string): TaxIdentifierResult;
336
386
  export declare const CURRENT_RELEASE_MERKLE_ROOT: string;
337
387
  export declare const MERKLE_ROOT_OKF_V2: string;
338
388
 
389
+ export interface CleanNumericAmountOptions {
390
+ strict?: boolean;
391
+ fieldName?: string;
392
+ interpretCreditAsNegative?: boolean;
393
+ }
394
+
395
+ export declare class MalformedNumericInputError extends Error {
396
+ code: 'MALFORMED_NUMERIC_INPUT';
397
+ field: string;
398
+ rawValue: any;
399
+ constructor(val: any, fieldName?: string);
400
+ }
401
+
402
+ export declare class MissingMandatoryParameterError extends Error {
403
+ code: 'MISSING_MANDATORY_PARAMETER';
404
+ field: string;
405
+ functionName: string;
406
+ constructor(fieldName: string, functionName: string);
407
+ }
408
+
409
+ export interface ToIntegerPaiseOptions {
410
+ fieldName?: string;
411
+ strict?: boolean;
412
+ strictSubPaisa?: boolean;
413
+ }
414
+
415
+ export declare function assertMandatoryNumeric(val: any, fieldName: string, functionName: string, options?: CleanNumericAmountOptions): number;
416
+ export declare function toIntegerPaise(amount: number | string, options?: string | ToIntegerPaiseOptions): number;
417
+ export declare function fromIntegerPaise(paise: number): number;
339
418
  export declare function roundToPaisa(amount: number | string): number;
340
419
  export declare function roundSection288B(amount: number | string): number;
420
+ export declare function cleanNumericAmount(val: any, options?: CleanNumericAmountOptions): number;
341
421
  export declare function calculateCorporateTaxMatVsConcessional(payload?: any): any;
342
422
  export declare function evaluatePlaceOfSupplyAndLut(payload?: any): any;
343
423
  export declare function calculateTransferPricingAlp(payload?: any): any;
344
424
  export declare function evaluateSection79LossContinuity(payload?: any): any;
345
425
  export declare function evaluateSection281TaxClearance(payload: any): any;
346
426
  export declare function revalueForeignExchangeIndAs109(payload?: any): any;
427
+ export declare function calculateBusinessCombinationsIndAs103(payload?: any): any;
428
+ export declare function calculateImpairmentIndAs36(payload?: any): any;
429
+ export declare function calculateRevenueAllocationIndAs115(payload?: any): any;
430
+ export declare function calculateLeaseAmortizationIndAs116(payload?: any): any;
431
+ export declare function calculateExpectedCreditLossIndAs109(payload?: any): any;
432
+ export declare function calculateEsopAmortizationIndAs102(payload?: any): any;
433
+ export declare function calculateDeferredTaxIndAs12(payload?: any): any;
434
+ export declare function evaluateProvisionsAndContingenciesIndAs37(payload?: any): any;
435
+ export declare function calculateForeignCurrencyIndAs21(payload?: any): any;
436
+ export declare function resolveMissingPanPenaltyFloor(params?: any): any;
347
437
  export declare function evaluateSection194Q(payload: any): any;
348
438
  export declare function evaluateSection194C(payload: any): any;
349
439
  export declare function evaluateSection194H(payload: any): any;
@@ -362,6 +452,9 @@ export declare function evaluateSection206C1H(payload: any): any;
362
452
  export declare function evaluateSection43bH(payload: any): any;
363
453
  export declare function calculateMsmeCompoundInterest(payload: any): any;
364
454
  export declare function calculateAdvanceTaxAndInterest(payload: any): any;
455
+ export declare function calculateRule42InputServiceReversal(payload: any): any;
456
+ export declare function reconcileRule42AnnualTrueUp(payload: any): any;
457
+ export declare function calculateRule43CapitalGoodsReversal(payload: any): any;
365
458
  export declare function calculateGstItcApportionmentRule42_43(payload: any): any;
366
459
  export declare function evaluateCrossBorderRemittance(payload: any): any;
367
460
  export declare function getRbiBankRateForDate(dateString?: string): number;
@@ -423,4 +516,387 @@ export declare function ignorePackageUpdate(
423
516
  versionToIgnore: string
424
517
  ): { status: 'SUCCESS' | 'ERROR'; ignoredVersion: string; error?: string };
425
518
 
519
+ export interface DaybookVoucherInput {
520
+ date: string;
521
+ voucherNo?: string;
522
+ voucherType?: string;
523
+ partyName: string;
524
+ partyPan?: string | null;
525
+ partyGstin?: string | null;
526
+ grossAmount: number;
527
+ gstAmount?: number;
528
+ tdsDeducted?: number;
529
+ }
530
+
531
+ export interface ReconcileDaybookOptions {
532
+ buyerTurnoverCr?: number | null;
533
+ disallowancePercent?: number;
534
+ corporateTaxRatePercent?: number;
535
+ delayedInterestRateMonthlyPercent?: number;
536
+ auditDate?: string | null;
537
+ }
538
+
539
+ export interface DaybookAuditSummary {
540
+ totalVouchersScanned: number;
541
+ uniqueVendorsCount: number;
542
+ vendorsExceeding50LCount: number;
543
+ vendorsWithExceptionsCount: number;
544
+ totalPurchasesInr: number;
545
+ totalExcessPurchasesOver50LInr: number;
546
+ totalTdsPayableInr: number;
547
+ totalTdsDeductedInr: number;
548
+ totalTdsShortfallInr: number;
549
+ totalSection40aDisallowanceInr: number;
550
+ totalEstimatedTaxImpactInr: number;
551
+ totalSection201InterestInr: number;
552
+ totalAuditExposureInr: number;
553
+ statutoryAuthority: string;
554
+ isAuthorizedToDisburse: boolean;
555
+ }
556
+
557
+ export interface ReconcileDaybookResult {
558
+ auditSummary: DaybookAuditSummary;
559
+ exceptionVendors: any[];
560
+ compliantVendors: any[];
561
+ allVendors: any[];
562
+ auditedVouchers: any[];
563
+ }
564
+
565
+ export declare function parseTallyDaybookCsv(csvText: string): DaybookVoucherInput[];
566
+ export declare function parseTallyDaybookXml(xmlText: string): DaybookVoucherInput[];
567
+ export declare function reconcile194QDaybook(
568
+ vouchers: DaybookVoucherInput[],
569
+ options?: ReconcileDaybookOptions
570
+ ): ReconcileDaybookResult;
571
+ export declare function generateTally194QJournalXml(
572
+ reconciliationResult: ReconcileDaybookResult,
573
+ options?: { voucherDate?: string; creditLedgerName?: string; companyName?: string }
574
+ ): string;
575
+ export declare function generateAuditMarkdownReport(
576
+ reconciliationResult: ReconcileDaybookResult
577
+ ): string;
578
+ export declare function getIndianFinancialYear(dateStr: string): string;
579
+
580
+ export interface ZohoBillRecord {
581
+ source: string;
582
+ rowNumber: number;
583
+ billId?: string | null;
584
+ billNumber: string;
585
+ exactKey: string;
586
+ alphaNumericKey: string;
587
+ billDate: string | null;
588
+ dueDate: string | null;
589
+ vendorName: string;
590
+ vendorGstin: string | null;
591
+ vendorPan: string | null;
592
+ isGstinValid: boolean;
593
+ status: string;
594
+ category: string;
595
+ isBlocked17_5: boolean;
596
+ taxableAmountInr: number;
597
+ cgstInr: number;
598
+ sgstInr: number;
599
+ igstInr: number;
600
+ totalTaxInr: number;
601
+ totalAmountInr: number;
602
+ balanceInr: number;
603
+ isFullyPaid: boolean;
604
+ }
605
+
606
+ export interface Gstr2bRecord {
607
+ source: string;
608
+ docType: 'INVOICE' | 'CREDIT_NOTE' | 'DEBIT_NOTE';
609
+ invoiceNumber: string;
610
+ originalInvoiceNumber?: string;
611
+ exactKey: string;
612
+ alphaNumericKey: string;
613
+ invoiceDate: string | null;
614
+ supplierGstin: string | null;
615
+ supplierPan: string | null;
616
+ supplierName: string;
617
+ recipientGstin: string;
618
+ posStateCode: string;
619
+ isRcm: boolean;
620
+ itcAvailable: boolean;
621
+ itcRevReason?: string | null;
622
+ taxableAmountInr: number;
623
+ igstInr: number;
624
+ cgstInr: number;
625
+ sgstInr: number;
626
+ cessInr: number;
627
+ totalTaxInr: number;
628
+ totalAmountInr: number;
629
+ }
630
+
631
+ export interface ReconcileZohoGstr2bOptions {
632
+ toleranceInr?: number;
633
+ asOfDate?: string;
634
+ recipientGstin?: string | null;
635
+ recipientTaxScheme?: 'REGULAR' | 'COMPOSITION' | 'UNKNOWN' | 'INDETERMINATE';
636
+ recipientRegisteredStates?: string[];
637
+ recipientRegisteredGstins?: string[];
638
+ paymentAppropriationMethod?: 'PROPORTIONATE' | 'VALUE_FIRST' | 'TAX_FIRST';
639
+ minimumEclBalanceInr?: number;
640
+ eclLedgerHistory?: Array<{ date: string; balanceInr: number }>;
641
+ eclUtilizationStatus?: 'UTILIZED' | 'UNUTILIZED' | 'UNKNOWN';
642
+ goodsInTransitWindowDays?: number;
643
+ }
644
+
645
+ export interface ReconcileZohoGstr2bParams {
646
+ zohoBills: ZohoBillRecord[] | string;
647
+ gstr2b: Gstr2bRecord[] | string | any;
648
+ options?: ReconcileZohoGstr2bOptions;
649
+ }
650
+
651
+ export type Gstr2bDisposition =
652
+ | 'MATCHED_ELIGIBLE'
653
+ | 'RCM_UNREGISTERED_SUPPLIER_ELIGIBLE'
654
+ | 'COMPOSITION_EXCLUDED_RCM_SUPPLY'
655
+ | 'RCM_COMPOSITION_INTERVENING_REGULARIZED_PAID'
656
+ | 'RCM_COMPOSITION_INTERVENING_REGULARIZED_UNPAID'
657
+ | 'MISMATCH_AMOUNT_VALUE'
658
+ | 'MATCHED_INELIGIBLE_STATUTORY_BLOCK_17_5'
659
+ | 'MATCHED_ROUTABLE_TO_BRANCH_GSTIN'
660
+ | 'MATCHED_INELIGIBLE_STRANDED_LOCAL_CGST_SGST'
661
+ | 'MATCHED_INELIGIBLE_PLACE_OF_SUPPLY_MISMATCH'
662
+ | 'GSTR2B_INELIGIBLE_FLAGGED_BY_GSTN'
663
+ | 'REQUIRES_HUMAN_VERIFICATION'
664
+ | 'MISSING_IN_GSTR2B'
665
+ | 'MISSING_IN_GSTR2B_TIMING'
666
+ | 'MISSING_IN_BOOKS'
667
+ | 'MISSING_IN_BOOKS_GOODS_IN_TRANSIT';
668
+
669
+ export interface JurisdictionDecisions {
670
+ taxClassification: 'INTRASTATE_CORRECT' | 'INTERSTATE_CORRECT' | 'ERRONEOUS_INTRASTATE_LEVY' | 'ERRONEOUS_INTERSTATE_LEVY' | 'INDETERMINATE';
671
+ recipientJurisdiction: 'FILING_GSTIN_MATCHES_POS' | 'REGISTERED_DISTINCT_PERSON_BRANCH' | 'UNREGISTERED_IN_POS_STATE' | 'INDETERMINATE';
672
+ itcEligibility: 'ELIGIBLE_NORMAL' | 'ELIGIBLE_IN_BRANCH_RETURN' | 'INELIGIBLE_STRANDED_LOCAL_LEVY' | 'INELIGIBLE_BLOCKED_SEC_17_5' | 'INELIGIBLE_DEFECTIVE_INVOICE' | 'INELIGIBLE_PORTAL_FLAGGED' | 'PROVISIONAL_PENDING_FILING' | 'INDETERMINATE';
673
+ operationalRouting: 'CLAIM_IN_CURRENT_GSTR3B_TABLE_4A5' | 'ROUTE_TO_BRANCH_GSTIN' | 'BOOK_AS_EXPENSE_NO_ITC' | 'REPORT_IN_GSTR3B_TABLE_4B1_PERMANENT_REVERSAL' | 'REQUEST_VENDOR_CREDIT_NOTE_AMENDMENT' | 'WITHHOLD_CLAIM_PENDING_SUPPLIER_GSTR1' | 'PHYSICAL_GOODS_RECEIPT_VERIFICATION_PENDING' | 'MANUAL_HUMAN_INVESTIGATION_REQUIRED';
674
+ }
675
+
676
+ export interface EvidenceProvenance {
677
+ provenanceId: string;
678
+ provenanceTimestamp: string;
679
+ source: {
680
+ sourceSystem: string;
681
+ docType: string;
682
+ billId: string | null;
683
+ billNumber: string | null;
684
+ rowNumber: number | null;
685
+ };
686
+ externalEvidence: {
687
+ sourceSystem: string;
688
+ presentInGstr2b: boolean;
689
+ invoiceNumber: string | null;
690
+ filingPeriod: string | null;
691
+ supplierFilingStatus: string;
692
+ portalRevReason: string | null;
693
+ };
694
+ matchingMethod: string;
695
+ statutoryBasis: {
696
+ governingStatute: string;
697
+ primarySection: string;
698
+ officialCitations: string[];
699
+ };
700
+ inputSnapshot: {
701
+ billNumber: string | null;
702
+ billDate: string | null;
703
+ vendorGstin: string | null;
704
+ taxableAmountInr: number;
705
+ totalTaxInr: number;
706
+ totalAmountInr: number;
707
+ balanceInr: number;
708
+ posStateCode: string | null;
709
+ isRcm: boolean;
710
+ category: string | null;
711
+ };
712
+ jurisdictionDecisions: {
713
+ taxClassification: string;
714
+ recipientJurisdiction: string;
715
+ itcEligibility: string;
716
+ operationalRouting: string;
717
+ };
718
+ uncertaintyAssessment: {
719
+ isCertain: boolean;
720
+ uncertaintyReason: string;
721
+ actionableRemedy: string;
722
+ };
723
+ governanceTrail: {
724
+ requiresHumanReview: boolean;
725
+ auditVerificationDate: string;
726
+ engineIdentity: string;
727
+ merkleSubstrateRoot: string;
728
+ isAuthorizedToDisburse: boolean;
729
+ };
730
+ }
731
+
732
+ export interface EclUtilizationInterval {
733
+ intervalIndex: number;
734
+ startDate: string;
735
+ endDate: string;
736
+ daysInInterval: number;
737
+ eclBalanceInr: number;
738
+ utilizedInr: number;
739
+ annualInterestRatePercent: number;
740
+ intervalInterestInr: number;
741
+ }
742
+
743
+ export interface EclUtilizationAuditResult {
744
+ totalInterestInr: number;
745
+ totalInterestPaise: number;
746
+ totalOverdueDays: number;
747
+ utilizedDaysCount: number;
748
+ zeroUtilizationDaysCount: number;
749
+ maxWrongfulUtilizationInr: number;
750
+ chronologicalIntervals: EclUtilizationInterval[];
751
+ explanation: string;
752
+ isAuthorizedToDisburse: boolean;
753
+ }
754
+
755
+ export interface ReconcileItem {
756
+ disposition: Gstr2bDisposition;
757
+ uncertaintyReason?: string;
758
+ itcStatus: string;
759
+ statutorySection: string;
760
+ vendorName: string;
761
+ vendorGstin: string | null;
762
+ billNumber: string;
763
+ billDate: string | null;
764
+ booksTaxableInr: number;
765
+ booksTaxInr: number;
766
+ gstr2bTaxableInr: number;
767
+ gstr2bTaxInr: number;
768
+ varianceTaxableInr: number;
769
+ varianceTaxInr: number;
770
+ isRule37Overdue: boolean;
771
+ daysElapsedSinceBill: number;
772
+ rule37Status: string;
773
+ rule37ReversalTaxInr: number;
774
+ rule37InterestInr: number;
775
+ rule37InterestExplanation?: string;
776
+ isReclaimableUponPayment: boolean;
777
+ isRcm?: boolean;
778
+ paymentAppropriationDetails?: Record<string, any> | null;
779
+ jurisdictionDecisions?: JurisdictionDecisions;
780
+ statutoryAction: string;
781
+ auditEvidence: Record<string, any>;
782
+ evidenceProvenance?: EvidenceProvenance;
783
+ }
784
+
785
+ export interface ReconcileZohoGstr2bSummary {
786
+ totalBooksBillsCount: number;
787
+ totalGstr2bRecordsCount: number;
788
+ matchedEligibleCount: number;
789
+ rcmUnregisteredEligibleCount: number;
790
+ compositionExcludedCount: number;
791
+ interveningRegularizedPaidCount: number;
792
+ interveningRegularizedUnpaidCount: number;
793
+ amountMismatchCount: number;
794
+ blocked17_5Count: number;
795
+ posMismatchCount: number;
796
+ routableToBranchCount: number;
797
+ strandedLocalCount: number;
798
+ gstr2bPortalIneligibleCount: number;
799
+ requiresHumanVerificationCount: number;
800
+ missingIn2bCount: number;
801
+ missingInBooksCount: number;
802
+ rule37OverdueCount: number;
803
+ totalBooksTaxableInr: number;
804
+ totalBooksTaxInr: number;
805
+ totalGstr2bTaxableInr: number;
806
+ totalGstr2bTaxInr: number;
807
+ eligibleItcInr: number;
808
+ rcmUnregisteredEligibleItcInr: number;
809
+ compositionExcludedItcInr: number;
810
+ interveningRegularizedTaxInr: number;
811
+ atRiskUnfiledItcInr: number;
812
+ blocked17_5ItcInr: number;
813
+ posMismatchItcInr: number;
814
+ routableToBranchItcInr: number;
815
+ strandedLocalItcInr: number;
816
+ gstr2bPortalIneligibleItcInr: number;
817
+ requiresHumanVerificationItcInr: number;
818
+ mismatchedItcInr: number;
819
+ missingInBooksTaxInr: number;
820
+ rule37ReversalAmountInr: number;
821
+ rule37InterestExposureInr: number;
822
+ paymentAppropriationMethod: 'PROPORTIONATE' | 'VALUE_FIRST' | 'TAX_FIRST';
823
+ paymentAppropriationLegalStatus: 'STATUTORY_MANDATE' | 'ACCOUNTING_ALLOCATION_ASSUMPTION';
824
+ recipientTaxScheme: 'REGULAR' | 'COMPOSITION' | 'INDETERMINATE';
825
+ minimumEclBalanceInr: number | null;
826
+ eclUtilizationStatus: 'UTILIZED' | 'UNUTILIZED' | 'UNKNOWN';
827
+ eclLedgerHistoryAudit: boolean;
828
+ cumulativePortfolioEclAudit?: any;
829
+ reconciliationStatus: 'FULLY_RECONCILED' | 'EXCEPTIONS_IDENTIFIED';
830
+ isAuthorizedToDisburse: boolean;
831
+ }
832
+
833
+ export interface ReconcileZohoGstr2bResult {
834
+ status: 'SUCCESS' | 'ERROR';
835
+ auditDate: string;
836
+ summary: ReconcileZohoGstr2bSummary;
837
+ reconciliationItems: ReconcileItem[];
838
+ }
839
+
840
+ export declare function parseZohoBillsCsv(csvText: string): ZohoBillRecord[];
841
+ export declare function parseZohoBillsJson(jsonData: any): ZohoBillRecord[];
842
+ export declare function parseGstr2bJson(gstr2bData: any): Gstr2bRecord[];
843
+ export declare function reconcileZohoGstr2b(params: ReconcileZohoGstr2bParams): ReconcileZohoGstr2bResult;
844
+ export declare function generateGstr2bAuditMarkdownReport(reconResult: ReconcileZohoGstr2bResult): string;
845
+ export declare function normalizeInvoiceNumber(raw: string): { exactKey: string; alphaNumericKey: string };
846
+ export declare function normalizeGstin(raw: string): { gstin: string | null; pan: string | null; stateCode: string | null; isValid: boolean };
847
+ export declare function calculateOverdueStartDate(billDateIso: string): string | null;
848
+ export declare function calculateEclUtilizationInterest(params: {
849
+ unreversedItcInr: number | string;
850
+ overdueStartDate: string;
851
+ asOfDate: string;
852
+ reversalDate?: string | null;
853
+ eclLedgerHistory?: Array<{ date: string; balanceInr: number }>;
854
+ annualInterestRate?: number;
855
+ }): EclUtilizationAuditResult;
856
+ export declare function calculatePortfolioEclUtilizationInterest(params: {
857
+ overdueBills: Array<any>;
858
+ eclLedgerHistory: Array<{ date: string; balanceInr: number }>;
859
+ asOfDate?: string;
860
+ annualInterestRate?: number;
861
+ }): any;
862
+ export declare function buildEvidenceProvenance(params: any): EvidenceProvenance;
863
+
864
+ export interface EmpanelmentCertificate {
865
+ certificateId: string;
866
+ attestationType: string;
867
+ attestationNotice: string;
868
+ attestationTimestamp: string;
869
+ merkleSubstrateRoot: string;
870
+ governingSpecification: string;
871
+ sectionsCount: number;
872
+ circularsCount: number;
873
+ formsCount: number;
874
+ citationsVerified: number;
875
+ freshnessStatus: 'FRESH_AND_AUDIT_READY' | 'ACTION_REQUIRED';
876
+ regulatoryHorizon: string;
877
+ empanelmentComplianceScore: string;
878
+ isAuthorizedToDisburse: false;
879
+ }
880
+
881
+ export interface WatchtowerReport {
882
+ status: 'SUCCESS' | 'FAILED';
883
+ watchtowerVersion: string;
884
+ auditTimestamp: string;
885
+ okfDirectory: string;
886
+ checks: {
887
+ schemaValidation: { status: 'PASSED' | 'FAILED'; sectionsScanned: number; circularsScanned: number; formsScanned: number; errors: string[] };
888
+ citationIntegrity: { status: 'PASSED' | 'FAILED'; totalCitations: number; validCitations: number; failedCitations: number; errors: any[] };
889
+ merkleImmutability: { status: 'PASSED' | 'FAILED'; computedRoot: string; matchesPinnedRoot: boolean; fileCount: number };
890
+ freshnessHorizon: { status: 'PASSED' | 'FAILED'; benchmarksEvaluated: number; benchmarksPassed: number; benchmarks: any[] };
891
+ statutoryInvariants: { status: 'PASSED' | 'FAILED'; disburseInvariantSatisfied: boolean };
892
+ };
893
+ certificate: EmpanelmentCertificate | null;
894
+ executionDurationMs: number;
895
+ }
896
+
897
+ export declare function runStatutoryWatchtower(options?: { okfDir?: string; verbose?: boolean }): Promise<WatchtowerReport>;
898
+
899
+
900
+
901
+
426
902