@mudraforge/statutory 2.9.0 → 2.11.0

package/src/constants.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Canonical Single-Source-of-Truth Constants for @mudraforge/statutory.
+ * Pure ESM module with zero Node.js/browser-specific dependencies.
+ * Safe to import across Node.js, Cloudflare Workers, browsers, and Edge runtimes.
+ *
+ * @license MIT
+ */
+
+export const STATUTORY_CLIENT_VERSION = '2.11.0';
+export const DEFAULT_BASE_URL = 'https://api.mudraforge.in';

package/src/index.js

@@ -21,20 +21,77 @@ import {
     evaluatePlaceOfSupplyAndLut,
     calculateTransferPricingAlp,
     evaluateSection79LossContinuity,
-    revalueForeignExchangeIndAs109
+    evaluateSection281TaxClearance,
+    revalueForeignExchangeIndAs109,
+    evaluateSection194Q,
+    evaluateSection194C,
+    evaluateSection194H,
+    evaluateSection194I,
+    evaluateSection194J,
+    evaluateSection194A,
+    evaluateSection194O,
+    evaluateSection194IA,
+    evaluateSection194IB,
+    evaluateSection194M,
+    evaluateSection194R,
+    evaluateSection43BStatutoryPayables,
+    calculateItcReversalRule37,
+    calculateRule37ASupplierNonFilingReversal,
+    evaluateSection206C1H,
+    evaluateSection43bH,
+    calculateMsmeCompoundInterest,
+    calculateAdvanceTaxAndInterest,
+    calculateGstItcApportionmentRule42_43,
+    evaluateCrossBorderRemittance,
+    generateMsme1AndScheduleThreeAging,
+    evaluateLowerDeductionCertificateValidity,
+    getRbiBankRateForDate,
+    DEFAULT_RBI_BANK_RATE,
+    MSMED_RATE_MULTIPLIER,
+    RBI_BANK_RATE_SCHEDULE,
+    AUTHORITATIVE_STATUTORY_RATES,
+    VALID_194J_CATEGORIES
 } from './calculators.js';
+import { 
+    getStatutoryOutcomes, 
+    explainStatutoryDisposition, 
+    STATUTORY_OUTCOMES_DICTIONARY,
+    enrichWithOutcomeExplanation
+} from './outcomes.js';
+
+import { STATUTORY_CLIENT_VERSION, DEFAULT_BASE_URL } from './constants.js';
+
+let defaultOkfDir = null;
+try {
+    if (typeof import.meta?.url === 'string' && import.meta.url.startsWith('file:')) {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        defaultOkfDir = path.resolve(__dirname, '..', 'okf');
+    }
+} catch (_) {
+    defaultOkfDir = null;
+}
+export const DEFAULT_LOCAL_OKF_DIR = defaultOkfDir;
+export { STATUTORY_CLIENT_VERSION, DEFAULT_BASE_URL };
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-export const DEFAULT_LOCAL_OKF_DIR = path.resolve(__dirname, '..', 'okf');
-export const DEFAULT_BASE_URL = 'https://api.mudraforge.in';
-export const STATUTORY_CLIENT_VERSION = '2.9.0';
+/**
+ * Current verified Merkle root digest for the active OKF v0.2 corpus.
+ */
+export const CURRENT_RELEASE_MERKLE_ROOT = 'sha256-bf547512a57f26eae9a5ebcb9f0ec41c397421366b1b4223ab9e17d282721ca7';
+export const MERKLE_ROOT_OKF_V2 = CURRENT_RELEASE_MERKLE_ROOT;
 
 /**
  * Pinned official release Merkle root digests.
  * Prevents unauthorized bundle substitution attacks even if an attacker controls the remote endpoint.
  */
 export const PINNED_RELEASE_ROOTS = new Set([
+    'sha256-feb1555f10c9f5c70de18ef340e0ba6cf1f060fb19cae866aa36240345c46f3a', // feat/rent-194ib-contract-194m (37 Sections across 5 Domains)
+    'sha256-02090e4063a863e3486401215469350c911dc0c9a24855e1d9db2903946aa644', // feat/perquisites-194r (35 Sections across 5 Domains)
+    'sha256-bd351719a8235c44f2bac87cc347423baa8ac3ecb74c0ee63d1fffa9f33dbebe', // feat/property-194ia (35 Sections across 5 Domains)
+    'sha256-fc208ff012bfc3044cfc6edc5fcbf1c0e445e387a8c7d806e271968b511919ce', // feat/mna-sec281 (34 Sections across 5 Domains)
+    'sha256-7f2bd99d81a261743773230d2ab3e21717ac9ca02a55c867545f5777b1a7d69f', // feat/statutory-43b-payroll (33 Sections across 5 Domains)
+    'sha256-bf547512a57f26eae9a5ebcb9f0ec41c397421366b1b4223ab9e17d282721ca7', // feat/ecommerce-194o (32 Sections across 5 Domains)
+    'sha256-b12fab61f0ddcc8852a7db1b4831151163d1d0ff97112168d8dccf693cfe70a7', // v2.11.0 Complete Accounts Payable (31 Sections across 5 Domains)
     'sha256-4bbe36c3db841b833dd2bebbd6c1c5ed735498e7b20d1221c323ceb211529fe0', // v2.9.0 Corporate Finance 5 Domains Merkle Root (29 Sections across 5 Domains)
     'sha256-3fb34bdcd34eec794b1f8e6abb2c0e0e87664746ec2f50ad2599c34bf57565b3', // v2.8.1 Finance Act, 2025 Section 206AB Sunset Root (24 Sections across 5 Domains)
     'sha256-239641de2bef05917673f693f9ba4d14bd5e137d64554fba5db87e426bc13e14', // v2.8.0 Deep Semantic Citation Merkle Root (24 Sections across 5 Domains)
@@ -886,7 +943,11 @@ export async function checkUpdates(options = {}) {
  * @returns {Promise<{ updateAvailable: boolean, currentVersion: string, latestVersion: string } | null>}
  */
 export async function checkForPackageUpdate(options = {}) {
-    if (!options.force && (process.env.NO_UPDATE_NOTIFIER === '1' || (process.env.CI === 'true' && !options.registryUrl))) {
+    if (!options.force && (
+        process.env.NO_UPDATE_NOTIFIER === '1' || 
+        process.env.MUDRA_NO_UPDATE_NOTIFIER === '1' || 
+        (process.env.CI === 'true' && !options.registryUrl)
+    )) {
         return null;
     }
 
@@ -922,7 +983,9 @@ export async function checkForPackageUpdate(options = {}) {
                     latestVersion = json.version;
                     if (cacheTtlMs > 0) {
                         try {
+                            const prev = fs.existsSync(cacheFile) ? JSON.parse(fs.readFileSync(cacheFile, 'utf8')) : {};
                             fs.writeFileSync(cacheFile, JSON.stringify({
+                                ...prev,
                                 lastChecked: Date.now(),
                                 latestVersion
                             }), 'utf8');
@@ -939,13 +1002,44 @@ export async function checkForPackageUpdate(options = {}) {
     if (!latestVersion) return null;
 
     const cmp = compareSemver(latestVersion, currentVersion);
+    const isIgnored = Boolean(cached?.ignoredVersion && cached.ignoredVersion === latestVersion);
+
     return {
-        updateAvailable: cmp > 0,
+        updateAvailable: cmp > 0 && (!isIgnored || Boolean(options.force)),
+        isIgnored,
         currentVersion,
         latestVersion
     };
 }
 
+/**
+ * Configure the CLI to ignore update notifications for a specific version.
+ * @param {string} versionToIgnore Package version to suppress notifications for
+ * @returns {{ status: 'SUCCESS' | 'ERROR', ignoredVersion: string, error?: string }}
+ */
+export function ignorePackageUpdate(versionToIgnore) {
+    if (!versionToIgnore || typeof versionToIgnore !== 'string') {
+        throw new Error('[@mudraforge/statutory] A valid version string is required to ignore update notifications.');
+    }
+    const cacheFile = path.join(os.tmpdir(), '.mudraforge_statutory_npm_update.json');
+    let current = {};
+    try {
+        if (fs.existsSync(cacheFile)) {
+            current = JSON.parse(fs.readFileSync(cacheFile, 'utf8')) || {};
+        }
+    } catch (_) {}
+
+    current.ignoredVersion = versionToIgnore.trim();
+    current.ignoredAt = Date.now();
+
+    try {
+        fs.writeFileSync(cacheFile, JSON.stringify(current, null, 2), 'utf8');
+        return { status: 'SUCCESS', ignoredVersion: versionToIgnore.trim() };
+    } catch (err) {
+        return { status: 'ERROR', ignoredVersion: versionToIgnore.trim(), error: err.message };
+    }
+}
+
 /**
  * Download and synchronize the latest OKF knowledge bundle to disk.
  * Hardened with:
@@ -1574,9 +1668,10 @@ export class StatutoryClient {
     async calculate(payload = {}, options = {}) {
         if (!this.apiKey) {
             const err = new Error(
-                '[@mudraforge/statutory] Deterministic calculation engines (Section 194Q excess math, ' +
-                'MSMED 3x RBI compounding interest, Section 194J FTS vs Professional) require an Enterprise API key.\n' +
-                'Direct contact is required: email hello@mudraforge.in or support@mudraforge.in to request access.'
+                '[@mudraforge/statutory] The hosted cloud calculation endpoint (\'/api/v1/statutory/calculate\') requires an Enterprise API key.\n' +
+                'To calculate deterministically offline without an API key or remote server, import pure calculation functions directly:\n' +
+                '  import { calculateCorporateTaxMatVsConcessional, evaluatePlaceOfSupplyAndLut, calculateTransferPricingAlp, evaluateSection79LossContinuity, revalueForeignExchangeIndAs109 } from \'@mudraforge/statutory\';\n' +
+                'For hosted cloud edge calculation access or custom enterprise models, contact hello@mudraforge.in or support@mudraforge.in.'
             );
             err.code = 'API_KEY_REQUIRED';
             err.contact = 'hello@mudraforge.in';
@@ -1656,7 +1751,8 @@ export class StatutoryClient {
             throw err;
         }
 
-        return await safeJsonParse(res, 'StatutoryClient.calculate');
+        const parsedResult = await safeJsonParse(res, 'StatutoryClient.calculate');
+        return enrichWithOutcomeExplanation(parsedResult, { ...options, verbose: options.verbose || payload.verbose });
     }
 
     /**
@@ -1750,6 +1846,153 @@ export class StatutoryClient {
     revalueForeignExchangeIndAs109(payload) {
         return revalueForeignExchangeIndAs109(payload);
     }
+
+    /**
+     * Section 194Q: Deduction of tax at source on purchase of goods exceeding ₹50 Lakh.
+     */
+    evaluateSection194Q(payload) {
+        return evaluateSection194Q(payload);
+    }
+
+    /**
+     * Section 194C: Withholding on contractor and sub-contractor payments.
+     */
+    evaluateSection194C(payload) {
+        return evaluateSection194C(payload);
+    }
+
+    /**
+     * Section 194H: Withholding on commission and brokerage payments.
+     */
+    evaluateSection194H(payload) {
+        return evaluateSection194H(payload);
+    }
+
+    /**
+     * Section 194I: Withholding on rent (land/building vs plant/machinery).
+     */
+    evaluateSection194I(payload) {
+        return evaluateSection194I(payload);
+    }
+
+    /**
+     * Section 194J: Withholding on professional and technical services (FTS).
+     */
+    evaluateSection194J(payload) {
+        return evaluateSection194J(payload);
+    }
+
+    /**
+     * Section 194A: Withholding on interest other than interest on securities.
+     */
+    evaluateSection194A(payload) {
+        return evaluateSection194A(payload);
+    }
+
+    /**
+     * Section 194O: E-commerce operator marketplace withholding & 194Q/206C(1H) override.
+     */
+    evaluateSection194O(payload) {
+        return evaluateSection194O(payload);
+    }
+
+    /**
+     * Section 194-IA: Immovable property transfer TDS (higher of consideration or SDV) & Form 26QB.
+     */
+    evaluateSection194IA(payload) {
+        return evaluateSection194IA(payload);
+    }
+
+    /**
+     * Section 194-IB: Individual/HUF rent TDS, 2% rate cut, Form 26QC, and Section 194-IB(4) last-month rent ceiling.
+     */
+    evaluateSection194IB(payload) {
+        return evaluateSection194IB(payload);
+    }
+
+    /**
+     * Section 194M: Individual/HUF contract/commission/professional TDS, 2% rate cut, Form 26QD, and 50L threshold.
+     */
+    evaluateSection194M(payload) {
+        return evaluateSection194M(payload);
+    }
+
+    /**
+     * Section 194R: Benefit or perquisite in business or profession TDS, in-kind advance tax, and de minimis threshold.
+     */
+    evaluateSection194R(payload) {
+        return evaluateSection194R(payload);
+    }
+
+    /**
+     * Section 43B / Section 36(1)(va): Statutory payables disallowance & Supreme Court Checkmate Doctrine.
+     */
+    evaluateSection43B(payload) {
+        return evaluateSection43BStatutoryPayables(payload);
+    }
+
+    /**
+     * Section 281: M&A asset transfer tax clearance & voidability evaluation under CBDT Circular 04/2011.
+     */
+    evaluateSection281(payload) {
+        return evaluateSection281TaxClearance(payload);
+    }
+
+    /**
+     * Rule 37: 180-day vendor non-payment ITC reversal & Section 50(1) 18% interest.
+     */
+    calculateItcReversalRule37(payload) {
+        return calculateItcReversalRule37(payload);
+    }
+
+    /**
+     * Rule 37A: Reversal of ITC where supplier failed to furnish Form GSTR-3B by November 30.
+     */
+    calculateRule37ASupplierNonFilingReversal(payload) {
+        return calculateRule37ASupplierNonFilingReversal(payload);
+    }
+
+    /**
+     * MSMED Act Section 16: Compound interest with monthly rests at 3x RBI Bank Rate.
+     */
+    calculateMsmeCompoundInterest(payload) {
+        return calculateMsmeCompoundInterest(payload);
+    }
+
+    /**
+     * Section 43B(h): Year-end tax disallowance on overdue MSME invoices.
+     */
+    evaluateSection43bH(payload) {
+        return evaluateSection43bH(payload);
+    }
+
+    /**
+     * Section 195: Cross-border foreign remittance tax withholding.
+     */
+    evaluateCrossBorderRemittance(payload) {
+        return evaluateCrossBorderRemittance(payload);
+    }
+
+    /**
+     * Retrieve statutory outcomes and disposition codes.
+     * @param {string} [provision] Optional section code or provision alias
+     * @param {Object} [options]
+     */
+    async getOutcomes(provision = null, options = {}) {
+        return await getStatutoryOutcomes(provision, {
+            ...options,
+            baseUrl: this.baseUrl
+        });
+    }
+
+    /**
+     * Retrieve in-depth explanation and remediation steps for a disposition code.
+     * @param {string} codeOrQuery Disposition code (e.g. 'BUYER_TURNOVER_UNVERIFIED', 'INDETERMINATE')
+     * @param {Object} [options]
+     */
+    explain(codeOrQuery, options = {}) {
+        return explainStatutoryDisposition(codeOrQuery, options);
+    }
 }
 
 /**
@@ -2752,7 +2995,40 @@ export {
     evaluatePlaceOfSupplyAndLut,
     calculateTransferPricingAlp,
     evaluateSection79LossContinuity,
-    revalueForeignExchangeIndAs109
+    evaluateSection281TaxClearance,
+    revalueForeignExchangeIndAs109,
+    evaluateSection194Q,
+    evaluateSection194C,
+    evaluateSection194H,
+    evaluateSection194I,
+    evaluateSection194J,
+    evaluateSection194A,
+    evaluateSection194O,
+    evaluateSection194IA,
+    evaluateSection194IB,
+    evaluateSection194M,
+    evaluateSection194R,
+    evaluateSection43BStatutoryPayables,
+    calculateItcReversalRule37,
+    calculateRule37ASupplierNonFilingReversal,
+    evaluateSection206C1H,
+    evaluateSection43bH,
+    calculateMsmeCompoundInterest,
+    calculateAdvanceTaxAndInterest,
+    calculateGstItcApportionmentRule42_43,
+    evaluateCrossBorderRemittance,
+    generateMsme1AndScheduleThreeAging,
+    evaluateLowerDeductionCertificateValidity,
+    getRbiBankRateForDate,
+    DEFAULT_RBI_BANK_RATE,
+    MSMED_RATE_MULTIPLIER,
+    RBI_BANK_RATE_SCHEDULE,
+    AUTHORITATIVE_STATUTORY_RATES,
+    VALID_194J_CATEGORIES,
+    getStatutoryOutcomes,
+    explainStatutoryDisposition,
+    STATUTORY_OUTCOMES_DICTIONARY,
+    enrichWithOutcomeExplanation
 };