@mudraforge/statutory 2.4.2 → 2.5.0

package/okf/msme_commercial/statutory_disclosures_sec22/section.json

@@ -0,0 +1,65 @@
+{
+  "sectionId": "MSMED2006_SEC22_DISCLOSURE",
+  "sectionCode": "MSMED-SEC-22",
+  "aliases": [
+    "section 22",
+    "sec 22",
+    "msme disclosures",
+    "schedule iii msme",
+    "trade payables aging",
+    "caro 2020 msme",
+    "section 23 addback",
+    "notes to accounts msme"
+  ],
+  "governingStatute": "Micro, Small and Medium Enterprises Development Act, 2006 read with Companies Act, 2013 Schedule III",
+  "statutorySection": "Section 22 of MSMED Act, 2006 read with Section 23 of MSMED Act, 2006 and Schedule III Division I & II",
+  "title": "Mandatory statutory disclosures in annual audited financial statements regarding dues to Micro and Small Enterprises and tax non-deductibility of penal interest",
+  "effectivePeriod": {
+    "validFrom": "2006-10-02",
+    "validTo": "OPEN_ENDED",
+    "annualReset": "Annual Financial Year-End Audited Financial Statements (March 31)"
+  },
+  "plainTextSummary": "Section 22 of the MSMED Act, 2006 mandates that any buyer required to have its accounts audited under any law must furnish five specific disclosures in its annual financial statements regarding trade payables to micro and small enterprises: (1) Principal and interest due remaining unpaid at year-end, (2) Interest paid along with delayed payments made during the year, (3) Interest due and payable for delays without added interest, (4) Interest accrued and remaining unpaid at year-end, and (5) Further interest remaining due and payable in succeeding years. In parallel, Schedule III of the Companies Act, 2013 prescribes a mandatory Trade Payables Aging Schedule segregating MSME dues (undisputed and disputed) into buckets: less than 1 year, 1-2 years, 2-3 years, and more than 3 years. Under Section 23 of the MSMED Act, compound penal interest payable or paid under Section 16 is strictly prohibited from being claimed as an income tax deduction, requiring an explicit book-to-tax add-back.",
+  "keyStatutoryThresholds": {
+    "mandatoryDisclosureCount": 5,
+    "scheduleIiiAgingBuckets": [
+      "Less than 1 year",
+      "1-2 years",
+      "2-3 years",
+      "More than 3 years"
+    ],
+    "disputeSegregation": "Mandatory separate aging disclosure for Undisputed MSME dues vs. Disputed MSME dues",
+    "taxAddbackMandate": "Section 23 strictly disallows Section 16 penal interest under Income-tax Act, 1961 (and Act 2025)",
+    "statutoryAuditVerification": "CARO 2020 Clause (xvi)(d) / (xix) requires statutory auditors to verify material uncertainty on settlement of MSME payables",
+    "applicableEntities": "All corporate and non-corporate entities subject to statutory audit having transactions with registered Micro/Small enterprises"
+  },
+  "officialCitations": [
+    {
+      "authority": "Ministry of Law and Justice",
+      "instrument": "Micro, Small and Medium Enterprises Development Act, 2006 (Act No. 27 of 2006)",
+      "subject": "Section 22: Requirement to specify unpaid amount with interest in the annual statement of accounts & Section 23: Interest not to be allowed as deduction from income",
+      "officialUrl": "https://msme.gov.in"
+    },
+    {
+      "authority": "Ministry of Corporate Affairs (MCA)",
+      "instrument": "Companies Act, 2013 Schedule III (Division I & II Amendment Notification G.S.R. 207(E) dated 24 March 2021)",
+      "subject": "Mandatory Trade Payables Aging Schedule Disclosures",
+      "officialUrl": "https://www.mca.gov.in"
+    },
+    {
+      "authority": "Institute of Chartered Accountants of India (ICAI)",
+      "instrument": "Guidance Note on Division I, II and III of Schedule III to the Companies Act, 2013",
+      "subject": "Accounting and Disclosure of Dues to Micro and Small Enterprises",
+      "officialUrl": "https://www.icai.org"
+    }
+  ],
+  "requiredDocumentChecklist": [
+    "Audited Balance Sheet Notes to Accounts for Trade Payables",
+    "Schedule III Trade Payables Aging Table (<1yr, 1-2yr, 2-3yr, >3yr)",
+    "General Ledger interest accrual schedule under Section 16 (compounded at 3x RBI Bank Rate)",
+    "Computation of Total Income showing Section 23 disallowance add-back in tax return",
+    "Confirmation letters from registered MSME suppliers on their status and outstanding dues"
+  ],
+  "tier": "PUBLIC_COMMONS_FREE",
+  "version": "2.4.0"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mudraforge/statutory",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Open Knowledge Format (OKF) client & AI Agent Skill for Indian and cross-border statutory tax provisions. Zero dependencies.",
   "type": "module",
   "main": "src/index.js",
@@ -36,7 +36,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/mondeep0123/mudraforge-statutory.git"
+    "url": "git+https://github.com/mondeep0123/mudraforge-statutory.git"
   },
   "homepage": "https://mudraforge.in/docs",
   "bugs": {

package/src/index.js

@@ -18,13 +18,18 @@ 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.4.2';
+export const STATUTORY_CLIENT_VERSION = '2.5.0';
 
 /**
  * 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-c32be389bfb82a52ffc40670b74103216c45f3b284c66d2b0020097eb36a25f9', // v2.5.0 Merkle Manifest Root (18 Sections across 5 Domains)
+    'sha256-f3b230a0774eb55d607403b5a656bbe2950a32d07145a46f0eb083232ec12986', // v2.6.0 Edge Sync Bundle Root (12 Sections across 5 Domains)
+    'sha256-4e9d9c064e55748dc6389eae1b5cb2fec1ad7f1c811097afd57e4fb0a6f6454e', // v2.6.0 Local Static Manifest Root (12 Sections across 5 Domains)
+    'sha256-b421910e35f4f16321f6a72382377db66a05ead521ff09d18a91ec9d534d0069', // v2.6.0 Edge Sync Bundle Root (11 Sections)
+    'sha256-dbbd3bc618b7807c4e76861329bd8c6903ef7f9cb28efc9a8693abc06915c9c1', // v2.6.0 Local Static Manifest Root (11 Sections)
     'sha256-7fe98cf432db5d31ee6b65bbb9d77575ce8c9192eec6f318e3ad3382af0ba900', // v2.5.0 Edge Sync Bundle Root
     'sha256-96089fe2835d0b9493293a1e5205e0b6b46f16771c9380d1f571969b453ba80d', // v2.4.0 Local Static Manifest Root
     'sha256-d9612074241f7c2cc1d05fa5eee254996f21db56ad1ab71ac36a084ffd4169e1'  // Baseline Release Root
@@ -34,14 +39,16 @@ export const PINNED_RELEASE_ROOTS = new Set([
  * Canonical MudraForge Statutory Root Ed25519 Public Key (SPKI DER Base64).
  * Used for verifying digital signatures on remote statutory update bundles.
  */
-export const MUDRAFORGE_STATUTORY_ROOT_PUBLIC_KEY = 'MCowBQYDK2VwAyEAw/XsE6QGtQzdq3EUP3xFpPFHu1x87VSNreXmXr6W17s=';
+export const MUDRAFORGE_STATUTORY_ROOT_PUBLIC_KEY = 'MCowBQYDK2VwAyEAYN4ZtkUBOwybN68SiVUI9YMDlEBNiCa1CAgUNx6rXUo=';
+export const LEGACY_STATUTORY_ROOT_PUBLIC_KEY = 'MCowBQYDK2VwAyEAw/XsE6QGtQzdq3EUP3xFpPFHu1x87VSNreXmXr6W17s=';
 
 /**
  * Authoritative set of trusted MudraForge Root Public Keys.
  * Public keys supplied through options that are not present in this set are rejected.
  */
 export const TRUSTED_STATUTORY_PUBLIC_KEYS = new Set([
-    MUDRAFORGE_STATUTORY_ROOT_PUBLIC_KEY
+    MUDRAFORGE_STATUTORY_ROOT_PUBLIC_KEY,
+    LEGACY_STATUTORY_ROOT_PUBLIC_KEY
 ]);
 
 /**
@@ -51,7 +58,15 @@ export const TRUSTED_STATUTORY_KEYS_METADATA = {
     [MUDRAFORGE_STATUTORY_ROOT_PUBLIC_KEY]: {
         keyId: 'mudraforge-root-2026-v1',
         algorithm: 'Ed25519',
-        purpose: 'MudraForge Open Knowledge Format Statutory Root Authority',
+        purpose: 'MudraForge Open Knowledge Format Statutory Root Authority (Active)',
+        validFrom: '2026-01-01T00:00:00Z',
+        validTo: '2027-12-31T23:59:59Z',
+        status: 'ACTIVE'
+    },
+    [LEGACY_STATUTORY_ROOT_PUBLIC_KEY]: {
+        keyId: 'mudraforge-root-2026-v0',
+        algorithm: 'Ed25519',
+        purpose: 'MudraForge Statutory Genesis Anchor (Legacy)',
         validFrom: '2026-01-01T00:00:00Z',
         validTo: '2027-12-31T23:59:59Z',
         status: 'ACTIVE'
@@ -305,6 +320,7 @@ export function lookupLocalStatute(section, okfDir = DEFAULT_LOCAL_OKF_DIR) {
     }
 
     const files = findJsonFilesRecursively(okfDir);
+    const records = [];
     for (const filePath of files) {
         let data;
         try {
@@ -312,55 +328,68 @@ export function lookupLocalStatute(section, okfDir = DEFAULT_LOCAL_OKF_DIR) {
         } catch (_) {
             continue;
         }
-
-        // Must be a valid statutory record with sectionCode
         if (!data || !data.sectionCode || typeof data.sectionCode !== 'string') continue;
+        records.push({ filePath, data });
+    }
+
+    let matchedRecord = null;
 
-        let isMatch = false;
+    // Pass 1: Authoritative exact match on sectionCode, sectionId, or aliases
+    for (const rec of records) {
+        const { data } = rec;
         const secCode = data.sectionCode.toLowerCase();
         const secId = (data.sectionId && typeof data.sectionId === 'string') ? data.sectionId.toLowerCase() : '';
 
         // 1. Direct sectionCode / sectionId match
         if (secCode === rawClean || (secId && secId === rawClean)) {
-            isMatch = true;
+            matchedRecord = rec;
+            break;
         }
 
         // 2. Normalized alphanumeric match (handles "17_5", "17(5)", "17-5", "msmed_15_16")
         if (
-            !isMatch && (
-                secCode.replace(/[()_-\s]+/g, '') === normalized ||
-                (secId && secId.replace(/[()_-\s]+/g, '') === normalized)
-            )
+            secCode.replace(/[()_-\s]+/g, '') === normalized ||
+            (secId && secId.replace(/[()_-\s]+/g, '') === normalized)
         ) {
-            isMatch = true;
+            matchedRecord = rec;
+            break;
         }
 
         // 3. Aliases match
         if (
-            !isMatch &&
             data.aliases &&
             data.aliases.some(
                 a => a.toLowerCase() === rawClean || a.toLowerCase().replace(/[()_-\s]+/g, '') === normalized
             )
         ) {
-            isMatch = true;
+            matchedRecord = rec;
+            break;
         }
+    }
 
-        // 4. Folder or filename match (handles "tds_goods_194q", "194Q-tds-on-purchase...")
-        if (!isMatch) {
+    // Pass 2: Heuristic folder or filename match (only if no authoritative code match found)
+    if (!matchedRecord) {
+        const escaped = normalized.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const tokenRegex = new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, 'i');
+        for (const rec of records) {
+            const { filePath } = rec;
             const fileName = path.basename(filePath).toLowerCase().replace(/\.json$/, '');
             const folderName = path.basename(path.dirname(filePath)).toLowerCase();
+
             if (
-                fileName.startsWith(rawClean) || fileName.startsWith(normalized) ||
-                folderName.includes(rawClean) || folderName.includes(normalized)
+                fileName.startsWith(`${rawClean}-`) || fileName.startsWith(`${normalized}-`) ||
+                tokenRegex.test(folderName) || tokenRegex.test(fileName)
             ) {
-                isMatch = true;
+                matchedRecord = rec;
+                break;
             }
         }
+    }
 
-        if (isMatch) {
-            // Attach supporting circulars and compliance forms if present in domain hierarchy
-            const parentDir = path.dirname(filePath);
+    if (matchedRecord) {
+        const { filePath, data } = matchedRecord;
+        // Attach supporting circulars and compliance forms if present in domain hierarchy
+        const parentDir = path.dirname(filePath);
             const circularsDir = path.join(parentDir, 'circulars');
             const formsDir = path.join(parentDir, 'forms');
 
@@ -370,7 +399,6 @@ export function lookupLocalStatute(section, okfDir = DEFAULT_LOCAL_OKF_DIR) {
             };
 
             return data;
-        }
     }
     return null;
 }
@@ -539,7 +567,6 @@ export async function syncOkf(options = {}) {
     assertSecureEndpoint(baseUrl);
 
     const okfDir = options.okfDir || DEFAULT_LOCAL_OKF_DIR;
-    const sectionsDir = path.join(okfDir, 'sections');
     const localManifest = getLocalManifest(okfDir);
 
     const bundleUrl = new URL('/api/v1/statutory/bundle.json', baseUrl);
@@ -627,6 +654,7 @@ export async function syncOkf(options = {}) {
         const fileHashes = {};
         const syncedSectionCodes = [];
         const seenCodes = new Set();
+        const stagedRelPaths = [];
 
         for (const statute of bundle.statutes) {
             // Verify core required statutory fields
@@ -640,20 +668,30 @@ export async function syncOkf(options = {}) {
             }
             seenCodes.add(codeKey);
 
-            const fileName = resolveSafeStatuteFilename(statute);
-            const targetPath = path.resolve(stagingDir, fileName);
+            // Determine relative deployment target:
+            // If statute provides relPath, preserve domain hierarchy (e.g. "direct_tax/tds_goods_194q/section.json")
+            // Otherwise, fall back to flat "sections/<filename>.json" for legacy compatibility
+            const relTarget = statute.relPath 
+                ? statute.relPath.replace(/\\/g, '/')
+                : path.join('sections', resolveSafeStatuteFilename(statute));
+
+            const targetPath = path.resolve(stagingDir, relTarget);
 
             // Path Traversal Containment Assertion
             if (!targetPath.startsWith(path.resolve(stagingDir) + path.sep)) {
-                throw new Error(`[@mudraforge/statutory] Security violation: Path traversal detected in filename "${fileName}".`);
+                throw new Error(`[@mudraforge/statutory] Security violation: Path traversal detected in target "${relTarget}".`);
             }
 
+            fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+
             const jsonStr = JSON.stringify(statute, null, 2);
             fs.writeFileSync(targetPath, jsonStr, 'utf8');
 
+            const fileName = resolveSafeStatuteFilename(statute);
             const fileHash = crypto.createHash('sha256').update(jsonStr).digest('hex');
             fileHashes[fileName] = fileHash;
             syncedSectionCodes.push(statute.sectionCode);
+            stagedRelPaths.push(relTarget);
         }
 
         // 2.5 Cryptographic Root Merkle Digest Verification
@@ -694,7 +732,14 @@ export async function syncOkf(options = {}) {
             const isPinned = PINNED_RELEASE_ROOTS.has(bundle.rootHash);
 
             if (!isSignatureValid && !isPinned) {
-                throw new Error(`[@mudraforge/statutory] Security violation: Untrusted bundle rootHash "${bundle.rootHash}". Bundle is neither cryptographically signed by MudraForge Root Authority nor pinned in authorized release roots. Set options.allowUnverifiedRoot=true for local non-production fixtures.`);
+                const isEdgeNewer = bundle.okfVersion && compareSemver(bundle.okfVersion, STATUTORY_CLIENT_VERSION) >= 0;
+                const remediation = isEdgeNewer
+                    ? `The remote legal bundle (OKF v${bundle.okfVersion}) has a newer cryptographic release root than recognized by your installed package (v${STATUTORY_CLIENT_VERSION}).\n` +
+                      `  To receive the updated release roots and trust anchors, update your client:\n` +
+                      `    npm install @mudraforge/statutory@latest\n` +
+                      `    npx @mudraforge/statutory@latest sync`
+                    : `Bundle is neither cryptographically signed by MudraForge Root Authority nor pinned in authorized release roots. Set options.allowUnverifiedRoot=true for local non-production fixtures.`;
+                throw new Error(`[@mudraforge/statutory] Security violation: Untrusted bundle rootHash "${bundle.rootHash}". ${remediation}`);
             }
         }
 
@@ -720,19 +765,18 @@ export async function syncOkf(options = {}) {
         }
 
         // 3. Atomically deploy from staging to destination
-        fs.mkdirSync(sectionsDir, { recursive: true });
-
-        const stagedFiles = fs.readdirSync(stagingDir);
-        for (const stagedFile of stagedFiles) {
-            const srcPath = path.join(stagingDir, stagedFile);
-            const destPath = path.join(sectionsDir, stagedFile);
+        for (const relTarget of stagedRelPaths) {
+            const srcPath = path.join(stagingDir, relTarget);
+            const destPath = path.join(okfDir, relTarget);
 
             // Safety assertion on destination path containment
             const resolvedDest = path.resolve(destPath);
-            if (!resolvedDest.startsWith(path.resolve(sectionsDir) + path.sep)) {
-                throw new Error(`[@mudraforge/statutory] Security violation: Destination path traversal detected in "${stagedFile}".`);
+            if (!resolvedDest.startsWith(path.resolve(okfDir) + path.sep)) {
+                throw new Error(`[@mudraforge/statutory] Security violation: Destination path traversal detected in "${relTarget}".`);
             }
 
+            fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
             try {
                 fs.renameSync(srcPath, destPath);
             } catch {
@@ -742,12 +786,20 @@ export async function syncOkf(options = {}) {
         }
 
         // 4. Write verified manifest
+        const manifestDomains = {};
+        for (const statute of bundle.statutes) {
+            const domain = statute.domain || (statute.relPath ? statute.relPath.split('/')[0] : 'sections');
+            if (!manifestDomains[domain]) manifestDomains[domain] = [];
+            if (statute.sectionCode) manifestDomains[domain].push(statute.sectionCode);
+        }
+
         const manifest = {
             okfVersion: bundle.okfVersion,
             publishedAt: bundle.publishedAt || new Date().toISOString(),
             rootHash: bundle.rootHash,
             totalSections: bundle.statutes.length,
             changelog: bundle.changelog || 'Synchronized from Cloudflare Edge API',
+            domains: manifestDomains,
             sections: syncedSectionCodes
         };
         fs.writeFileSync(path.join(okfDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
@@ -1193,3 +1245,201 @@ export class StatutoryClient {
         return await syncOkf({ baseUrl: this.baseUrl, okfDir: this.okfDir });
     }
 }
+
+/**
+ * Standard Indian State & Union Territory Codes (Census 2011 / GSTN 2-digit prefix).
+ */
+export const INDIAN_STATE_CODES = {
+    '01': 'Jammu & Kashmir',
+    '02': 'Himachal Pradesh',
+    '03': 'Punjab',
+    '04': 'Chandigarh',
+    '05': 'Uttarakhand',
+    '06': 'Haryana',
+    '07': 'Delhi',
+    '08': 'Rajasthan',
+    '09': 'Uttar Pradesh',
+    '10': 'Bihar',
+    '11': 'Sikkim',
+    '12': 'Arunachal Pradesh',
+    '13': 'Nagaland',
+    '14': 'Manipur',
+    '15': 'Mizoram',
+    '16': 'Tripura',
+    '17': 'Meghalaya',
+    '18': 'Assam',
+    '19': 'West Bengal',
+    '20': 'Jharkhand',
+    '21': 'Odisha',
+    '22': 'Chhattisgarh',
+    '23': 'Madhya Pradesh',
+    '24': 'Gujarat',
+    '26': 'Dadra & Nagar Haveli and Daman & Diu',
+    '27': 'Maharashtra',
+    '29': 'Karnataka',
+    '30': 'Goa',
+    '31': 'Lakshadweep',
+    '32': 'Kerala',
+    '33': 'Tamil Nadu',
+    '34': 'Puducherry',
+    '35': 'Andaman & Nicobar Islands',
+    '36': 'Telangana',
+    '37': 'Andhra Pradesh',
+    '38': 'Ladakh',
+    '97': 'Other Territory',
+    '99': 'Centre Jurisdiction'
+};
+
+/**
+ * Statutory 4th character legal status classification for Indian Permanent Account Numbers (PAN).
+ * Enacted under Section 139A of the Income-tax Act, 1961 read with Rule 114 of Income Tax Rules.
+ */
+export const PAN_ENTITY_TYPES = {
+    'P': { code: 'P', name: 'Individual', isIndividualOrHuf: true, standard194cRatePercent: 1.0 },
+    'H': { code: 'H', name: 'Hindu Undivided Family (HUF)', isIndividualOrHuf: true, standard194cRatePercent: 1.0 },
+    'C': { code: 'C', name: 'Company', isIndividualOrHuf: false, standard194cRatePercent: 2.0 },
+    'F': { code: 'F', name: 'Partnership Firm / LLP', isIndividualOrHuf: false, standard194cRatePercent: 2.0 },
+    'T': { code: 'T', name: 'Trust', isIndividualOrHuf: false, standard194cRatePercent: 2.0 },
+    'A': { code: 'A', name: 'Association of Persons (AOP)', isIndividualOrHuf: false, standard194cRatePercent: 2.0 },
+    'B': { code: 'B', name: 'Body of Individuals (BOI)', isIndividualOrHuf: false, standard194cRatePercent: 2.0 },
+    'L': { code: 'L', name: 'Local Authority', isIndividualOrHuf: false, standard194cRatePercent: 2.0 },
+    'J': { code: 'J', name: 'Artificial Juridical Person', isIndividualOrHuf: false, standard194cRatePercent: 2.0 },
+    'G': { code: 'G', name: 'Government Agency', isIndividualOrHuf: false, standard194cRatePercent: 2.0 }
+};
+
+const BASE36_ALPHANUMERIC = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+/**
+ * Validates the check digit of a 15-character Goods and Services Tax Identification Number (GSTIN)
+ * using the official ISO/IEC 7064 Mod 36, 36 check digit algorithm.
+ * 
+ * Offline, zero-dependency, and deterministic. Requires zero network calls.
+ * 
+ * @param {string} gstin 15-character alphanumeric GSTIN string
+ * @returns {boolean} True if the 15th character exactly matches the calculated check character
+ */
+export function isValidGstinChecksum(gstin) {
+    if (!gstin || typeof gstin !== 'string') return false;
+    const clean = gstin.trim().toUpperCase();
+
+    // Structural syntax: State (2 digits) + PAN (10 chars) + Entity (1 char) + Z (1 char) + Check (1 char)
+    const pattern = /^\d{2}[A-Z]{5}\d{4}[A-Z][A-Z\d]Z[A-Z\d]$/;
+    if (!pattern.test(clean)) return false;
+
+    let total = 0;
+    for (let i = 0; i < 14; i++) {
+        const val = BASE36_ALPHANUMERIC.indexOf(clean[i]);
+        if (val === -1) return false;
+        const factor = (i % 2 === 0) ? 1 : 2;
+        const product = val * factor;
+        total += Math.floor(product / 36) + (product % 36);
+    }
+
+    const expectedIndex = (36 - (total % 36)) % 36;
+    const expectedChar = BASE36_ALPHANUMERIC[expectedIndex];
+    return clean[14] === expectedChar;
+}
+
+/**
+ * Deterministically decodes an Indian Tax Identifier (PAN or GSTIN).
+ * 
+ * Capabilities:
+ * - Structural regular expression pattern validation
+ * - Offline ISO/IEC 7064 Mod 36, 36 checksum calculation for GSTIN
+ * - State code and name extraction from GSTIN prefix
+ * - Embedded 10-character PAN extraction from GSTIN positions 3..12
+ * - Statutory legal entity classification via 4th character of PAN (Individual, HUF, Company, Firm, etc.)
+ * - Statutory Section 194C withholding rate derivation (1% for Individual/HUF vs 2% for Other Entities)
+ * 
+ * Zero dependencies, 0-neuron, zero network calls.
+ * 
+ * @param {string} rawId PAN (10 characters) or GSTIN (15 characters)
+ * @returns {Object} Decoded tax entity metadata
+ */
+export function decodeTaxIdentifier(rawId) {
+    if (!rawId || typeof rawId !== 'string') {
+        return {
+            isValid: false,
+            error: 'Tax identifier must be a non-empty string.'
+        };
+    }
+
+    const clean = rawId.trim().toUpperCase();
+
+    // 1. Process 15-character GSTIN
+    if (clean.length === 15) {
+        const pattern = /^\d{2}[A-Z]{5}\d{4}[A-Z][A-Z\d]Z[A-Z\d]$/;
+        if (!pattern.test(clean)) {
+            return {
+                isValid: false,
+                type: 'GSTIN',
+                gstin: clean,
+                error: 'Malformed GSTIN format: expected 2 digits state + 10 chars PAN + 1 entity char + Z + 1 check char.'
+            };
+        }
+
+        const isChecksumValid = isValidGstinChecksum(clean);
+        const stateCode = clean.slice(0, 2);
+        const pan = clean.slice(2, 12);
+        const entityCode = pan[3];
+        const entityMeta = PAN_ENTITY_TYPES[entityCode] || {
+            code: entityCode,
+            name: 'Other Entity / Non-Individual',
+            isIndividualOrHuf: false,
+            standard194cRatePercent: 2.0
+        };
+
+        return {
+            isValid: isChecksumValid,
+            checksumValid: isChecksumValid,
+            type: 'GSTIN',
+            gstin: clean,
+            pan,
+            stateCode,
+            stateName: INDIAN_STATE_CODES[stateCode] || 'Unknown Territory',
+            entityCode,
+            entityType: entityMeta.name,
+            isIndividualOrHuf: entityMeta.isIndividualOrHuf,
+            standard194cRatePercent: entityMeta.standard194cRatePercent,
+            error: isChecksumValid ? null : 'GSTIN checksum mismatch under ISO/IEC 7064 Mod 36, 36.'
+        };
+    }
+
+    // 2. Process 10-character PAN
+    if (clean.length === 10) {
+        const panPattern = /^[A-Z]{5}\d{4}[A-Z]$/;
+        if (!panPattern.test(clean)) {
+            return {
+                isValid: false,
+                type: 'PAN',
+                pan: clean,
+                error: 'Malformed PAN format: expected 5 letters + 4 digits + 1 letter.'
+            };
+        }
+
+        const entityCode = clean[3];
+        const entityMeta = PAN_ENTITY_TYPES[entityCode] || {
+            code: entityCode,
+            name: 'Other Entity / Non-Individual',
+            isIndividualOrHuf: false,
+            standard194cRatePercent: 2.0
+        };
+
+        return {
+            isValid: true,
+            type: 'PAN',
+            pan: clean,
+            entityCode,
+            entityType: entityMeta.name,
+            isIndividualOrHuf: entityMeta.isIndividualOrHuf,
+            standard194cRatePercent: entityMeta.standard194cRatePercent,
+            error: null
+        };
+    }
+
+    return {
+        isValid: false,
+        error: `Invalid identifier length (${clean.length}): Expected 10 characters for PAN or 15 characters for GSTIN.`
+    };
+}
+

package/types/index.d.ts

@@ -190,3 +190,24 @@ export declare class StatutoryClient {
     checkUpdates(): Promise<UpdateInfo>;
     sync(): Promise<SyncResult>;
 }
+
+export interface TaxIdentifierResult {
+    isValid: boolean;
+    checksumValid?: boolean;
+    type?: 'GSTIN' | 'PAN';
+    gstin?: string;
+    pan?: string;
+    stateCode?: string;
+    stateName?: string;
+    entityCode?: string;
+    entityType?: string;
+    isIndividualOrHuf?: boolean;
+    standard194cRatePercent?: number;
+    error?: string | null;
+}
+
+export declare const INDIAN_STATE_CODES: Record<string, string>;
+export declare const PAN_ENTITY_TYPES: Record<string, { code: string; name: string; isIndividualOrHuf: boolean; standard194cRatePercent: number }>;
+export declare function isValidGstinChecksum(gstin: string): boolean;
+export declare function decodeTaxIdentifier(rawId: string): TaxIdentifierResult;
+