@mudraforge/statutory 2.10.0 → 2.12.1

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # MudraForge Statutory Architecture
 ## Grounding Financial AI in Deterministic Law & Open Knowledge
 
-> **MudraForge Statutory Bundle**: `v2.9.0`  
+> **MudraForge Statutory Bundle**: `v2.10.0`  
 > **Knowledge Specification**: Google Open Knowledge Format (OKF) specification (upstream v0.2)  
 > **License**: MIT (Public Knowledge Commons)  
 > **Status**: Public Beta  
@@ -143,7 +143,7 @@ The journey of an accounts payable transaction from incoming PDF invoice to gene
   3. *Temporal State Machine Evaluation*:
      - Verifies `transactionDate >= section.effectiveFrom`.
      - Evaluates `section.sunsetDate`. If $\text{transactionDate} \ge \text{sunsetDate}$ (as with Section 206C(1H) on 1 April 2025), transitions status to `SUNSET_SUPERSEDED` and halts execution.
-     - Evaluates `section.successorAct2025Mapping`. If $\text{transactionDate} \ge \text{2026-04-01}$, cross-compiles citation to the *Income-tax Act, 2025* codification (e.g. Section 194Q $\rightarrow$ Section 393(1), Table 8, Item (ii)).
+     - Evaluates `section.successorAct2025Mapping`. If $\text{transactionDate} \ge \text{2026-04-01}$, cross-compiles citation to the *Income-tax Act, 2025* codification (e.g. Section 194Q $\rightarrow$ Section 393(1), Table 1, Sl. No. 8(ii)).
 - **Outbound Payload**: Immutable `StatutoryRuleSnapshot` containing thresholds, rates, circular provisos, and successor mapping.
 - **Failure Modes & Degradation Handling**:
   - `ERR_SECTION_NOT_FOUND`: Specified statutory provision not indexed in active OKF manifest.
@@ -276,7 +276,7 @@ Large Language Models (LLMs) are stochastic token predictors. In corporate accou
    *Example*: **Section 206C(1H)** was omitted by the Finance Act, 2025 effective 1 April 2025. Standard model weights continue citing and enforcing sunset sections long after their legal expiration date because pre-training data lacks temporal enforcement boundaries.
 
 3. **Dual-Act Legislative Transition**:
-   India transitioned to the **Income-tax Act, 2025** (which took effect 1 April 2026), replacing familiar 1961 section numbers with new codifications (e.g., Section 194Q transitions to Section 393(1), Table 8, Item (ii)). Agents without a dual-act mapping layer hallucinate cross-statutory citations.
+   India transitioned to the **Income-tax Act, 2025** (which took effect 1 April 2026), replacing familiar 1961 section numbers with new codifications (e.g., Section 194Q transitions to Section 393(1), Table 1, Sl. No. 8(ii)). Agents without a dual-act mapping layer hallucinate cross-statutory citations.
 
 4. **The Failure of Messy Web Searches (Web RAG)**:
    When autonomous agents attempt to retrieve tax laws using automated search queries, they ingest conflicting third-party summaries: outdated SEO-optimized accounting blogs from 2018–2022, promotional vendor writeups, and unstructured discussion forums. These sources consistently miss crucial statutory provisos—such as CBDT Circular 13/2021 unbundling GST from TDS, or Ministry of MSME OM 2/1(5)/2021 excluding wholesale/retail traders. Web RAG introduces high latency, burns thousands of context tokens, and injects contradictory noise into agent reasoning.
@@ -459,9 +459,9 @@ When an autonomous agent (Antigravity, Cursor, Claude Code) receives a complianc
 
 ### Dual-Act Legislative Migration Matrix
 The OKF embeds a cross-compilation matrix forward-mapping the *Income-tax Act, 1961* to the *Income-tax Act, 2025*:
-- `194Q` $\rightarrow$ Section 393(1), Table 8, Item (ii)
-- `194J` $\rightarrow$ Section 393(1), Table 8, Item (iii)
-- `194C` $\rightarrow$ Section 393(1), Table 8, Item (i)
+- `194Q` $\rightarrow$ Section 393(1), Table 1, Sl. No. 8(ii)
+- `194J` $\rightarrow$ Section 393(1), Table 1, Sl. No. 6(iii)
+- `194C` $\rightarrow$ Section 393(1), Table 1, Sl. No. 8(i)
 
 Transactions dated before 1 April 2026 resolve under the 1961 Act; transactions on or after 1 April 2026 automatically compile under the 2025 Act codification.
 
@@ -477,7 +477,7 @@ Currently, the substrate indexes and provides deterministic ground truth across
 - **Section 194Q**: 0.1% TDS on purchase of goods exceeding ₹50 Lakhs cumulative annual threshold (calculating strictly on the excess over ₹50L).
 - **Section 206C(1H)**: TCS on sale of goods, with automated temporal interception of its **1 April 2025 sunset** under the Finance Act, 2025.
 - **Section 194J**: Fees for Technical Services (2% FTS) vs. Professional Fees (10%), enforcing standard 20% non-PAN penalty rates under Section 206AA(1)(iii) / Section 397(2)(a).
-- **Dual-Act Forward Mapping**: Complete cross-compilation matrix from *Income-tax Act, 1961* to the *Income-tax Act, 2025* (which took effect 1 April 2026), mapping sections seamlessly (e.g., Section 194Q → Section 393(1), Table 8, Item (ii)).
+- **Dual-Act Forward Mapping**: Complete cross-compilation matrix from *Income-tax Act, 1961* to the *Income-tax Act, 2025* (which took effect 1 April 2026), mapping sections seamlessly (e.g., Section 194Q → Section 393(1), Table 1, Sl. No. 8(ii)).
 
 ### 2. Indirect Tax & Procurement Compliance (GST)
 - **CGST Section 17(5)**: Comprehensive statutory negative list for Blocked Input Tax Credit (ITC)—including motor vehicles, corporate food & beverages, personal consumption, club memberships, and statutory exceptions/provisos.
@@ -592,7 +592,7 @@ Data traveling between tiers is encapsulated within a deterministic verification
 
 ```json
 {
-  "protocolVersion": "okf/2.9.0",
+  "protocolVersion": "okf/2.10.0",
   "domain": "direct_tax",
   "sectionCode": "194Q",
   "manifestDigest": "sha256-4bbe36c3db841b833dd2bebbd6c1c5ed735498e7b20d1221c323ceb211529fe0",
@@ -614,9 +614,9 @@ Data traveling between tiers is encapsulated within a deterministic verification
 ### 9.3 Edge Consistency & Eventual Consistency Resolution (Cloudflare KV)
 
 Cloudflare Workers KV provides global low-latency reads via eventual consistency across edge nodes. To prevent release skew during regulatory updates:
-1. *Immutable Version Tagging*: All statutory releases are written under unique semver namespaces (`statutory:releases:v2.9.0:...`).
+1. *Immutable Version Tagging*: All statutory releases are written under unique semver namespaces (`statutory:releases:v2.10.0:...`).
 2. *Atomic Manifest Flip*: The global pointer `statutory:active_release` is updated only after all 86 files across all domains are fully confirmed across edge replicas.
-3. *Cache-Control Invalidation*: Manifest responses carry strict validation headers (`ETag: "v2.9.0"`, `stale-while-revalidate=600`).
+3. *Cache-Control Invalidation*: Manifest responses carry strict validation headers (`ETag: "v2.10.0"`, `stale-while-revalidate=600`).
 4. *Local Fallback*: If Tier 2 returns HTTP 5xx or fails DNS resolution, Tier 1 and Tier 3 automatically fall back to the bundled local filesystem snapshot without failing the active business transaction.
 
 ### 9.4 Architectural Boundaries: The Autonomous Coprocessor vs. Stateless Subsystems
@@ -733,10 +733,10 @@ To prevent version skew across regions, the edge runtime employs an **Immutable
 1. **Immutable Artifact Keys**: Every section schema, circular, and form is stored under an immutable, version-tagged key:
    ```
    statutory:releases:<semver>:<domain>:<section_code>
-   # Example: statutory:releases:v2.9.0:direct_tax:194Q
+   # Example: statutory:releases:v2.10.0:direct_tax:194Q
    ```
    Once written to KV, the bytes for a specific semver key are permanently immutable.
-2. **Atomic Manifest Pointers**: Releases are indexed by a versioned root manifest (`statutory:manifests:v2.9.0`). The active pointer is switched only after all constituent keys are fully populated.
+2. **Atomic Manifest Pointers**: Releases are indexed by a versioned root manifest (`statutory:manifests:v2.10.0`). The active pointer is switched only after all constituent keys are fully populated.
 3. **Cache Invalidation & ETag Gates**: The manifest endpoint serves HTTP `ETag` validators with short edge TTLs (`Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600`). This ensures edge caches converge globally within minutes while allowing clients to detect release changes via deterministic SHA-256 root hash comparisons.
 - **Commercial Boundary**: Only the automated, continuously maintained edge update stream, neural discovery search, and deep deterministic calculator engines require an Enterprise API subscription post-beta.
 
@@ -744,7 +744,7 @@ To prevent version skew across regions, the edge runtime employs an **Immutable
 
 ## 12. Related Documents
 
-- [`DOMAIN_BREADTH_AND_DEPTH_COMPARISON.md`](./DOMAIN_BREADTH_AND_DEPTH_COMPARISON.md) — Authoritative matrix comparing the 4 starter domains against the full 11-domain sovereign roadmap.
+- [`DOMAIN_BREADTH_AND_DEPTH_COMPARISON.md`](./DOMAIN_BREADTH_AND_DEPTH_COMPARISON.md) — Authoritative matrix comparing the 5 starter domains against the full 11-domain sovereign roadmap.
 - [`VERIFICATION.md`](./VERIFICATION.md) — Formal verification report, TLA+ state machine model, mutation tests, and documented limitations.
 - [`ENTERPRISE_GOVERNANCE.md`](./ENTERPRISE_GOVERNANCE.md) — The Adesha governance architecture: single-use payment leases, Two-Generals banking recovery, and ERP writebacks.
-- [`README.md`](./README.md) — Quickstart, CLI commands, and installation guide.
+- [`README.md`](../README.md) — Quickstart, CLI commands, and installation guide.

package/docs/ARCHITECTURE_DECISIONS.md

@@ -12,7 +12,7 @@
 Developers, AI agents, and enterprise ERP integrations need access to Indian statutory provisions (such as Section 194Q, 194J, 206C(1H), MSMED 15/16, and GST 17(5)). Relying solely on a hosted remote API introduces network latency, availability risks, single-point-of-failure vulnerabilities, and developer friction (requiring API keys for basic lookups).
 
 ### Decision
-We bundle an offline starter package of 6 canonical provisions across 4 domains directly within the NPM package filesystem (`okf/`), validated by an immutable SHA-256 Merkle root digest. 
+We bundle an offline package of 29 canonical provisions across 5 domains directly within the NPM package filesystem (`okf/`), validated by an immutable SHA-256 Merkle root digest. 
 - Lookups in default or `mode: 'local'` execute entirely against local disk with zero network requests.
 - Hosted Cloudflare Anycast edge synchronization is provided on a best-effort basis during beta to discover real-time gazette updates and expanded unbundled provisions.
 - If edge sync is unreachable, callers automatically degrade to the verified local snapshot with an explicit `advisory` signal.
@@ -69,7 +69,7 @@ We establish three independent, non-interchangeable versioning dimensions:
 | :--- | :--- | :--- | :--- |
 | **`okfVersion`** | Knowledge Schema Structure | Incremented only when the JSON schema or metadata fields change (e.g., adding a required field). | `0.2.0` |
 | **`corpusRelease`** | Legal Corpus Snapshot | Incremented when statutory provisions, rates, or circulars are updated or added. | `2026.04.1` |
-| **`version`** (SemVer) | NPM Client SDK & CLI | Standard Semantic Versioning for the JavaScript library, CLI commands, and test runners. | `2.9.0` |
+| **`version`** (SemVer) | NPM Client SDK & CLI | Standard Semantic Versioning for the JavaScript library, CLI commands, and test runners. | `2.10.0` |
 
 ---
 
@@ -82,7 +82,7 @@ To maintain institutional credibility, public documentation must never blur the
 
 | Subsystem / Capability | Architectural Layer | Operational Status | Availability / Access | Verification Evidence |
 | :--- | :--- | :--- | :--- | :--- |
-| **Bundled OKF Statutory Corpus (29 Provisions across 5 Domains)** | Layer 1: Public Package | `PUBLIC_BUNDLED` | Immediate (Local repo & release candidate) | 80/80 test suites passing; SHA-256 Merkle root verified |
+| **Bundled OKF Statutory Corpus (29 Provisions across 5 Domains)** | Layer 1: Public Package | `PUBLIC_BUNDLED` | Immediate (Local repo & release candidate) | 88/88 test suites passing; SHA-256 Merkle root verified |
 | **Zero-Network CLI (`mudraforge-statutory`)** | Layer 1: Public Package | `PUBLIC_BUNDLED` | Immediate (Global / NPX) | `bin/cli.js` verified across Windows & Linux |
 | **Vendor-Neutral Conformance Suite** | Layer 1: Public Package | `PUBLIC_BUNDLED` | Immediate (`conformance/`) | 12/12 fixture tests passing |
 | **Local Query SDK (`src/index.js`)** | Layer 1: Public Package | `PUBLIC_BUNDLED` | Immediate (Node.js v18+) | Zero-dependency offline lookup and temporal checks |

package/docs/CASE_01_FORM_TEXT.txt

@@ -0,0 +1,48 @@
+INWARD INVOICE SLIP (TAX INVOICE)
+--------------------------------------------------------------------------------
+Supplier: Precision Castings Pvt. Ltd. | GSTIN: 27AAACP1234F1ZV (Maharashtra)
+PAN     : AAACP1234F (Company)         | MSME : UDYAM-MH-03-0019842 (Micro Mfr)
+Inv No  : PCPL/25-26/0541              | Date : 01-May-2025 (GRN: 01-May-2025)
+Terms   : PO-2025-0892 (Net 60 Days)   | Supply: HSN 732599 (Valve Castings)
+Basic   : ₹20,00,000.00                | IGST 18%: ₹3,60,000.00
+Total   : ₹23,60,000.00                | Place of Supply: Gujarat (Interstate)
+
+BUYER ERP CONTEXT (Zenith Engineering Pvt. Ltd.)
+--------------------------------------------------------------------------------
+Prior FY Turnover : ₹18.50 Crore (Exceeds ₹10 Cr 194Q Gate)
+YTD Purchases     : ₹45,00,000.00 prior to this bill (Excl. GST, on credit)
+PAN Status        : Active & Operative
+
+MUDRAFORGE ENGINE OUTPUT (STATUTORY DETERMINATION)
+--------------------------------------------------------------------------------
+1. Section 194Q TDS:
+   - Taxable Base : ₹15,00,000 (Excess over ₹50L; GST excluded per Cir 13/2021)
+   - TDS Rate     : 0.1% (Standard operative PAN rate)
+   - TDS Amount   : ₹1,500.00 (Exceeds ₹50L base; satisfies Section 288B multiple-of-10 rounding)
+
+2. MSMED Act Sec 15 & Sec 43B(h):
+   - Status       : Micro Manufacturer (NIC 24311)
+   - Credit Term  : 60-day term is void; capped at 45 days from GRN (01-May-2025)
+   - Cutoff Date  : 15-June-2025 (To avoid Sec 16 interest & 43B(h) disallowance)
+
+3. General Ledger Posting:
+   - Dr. Expense ₹20,00,000 | Dr. IGST ₹3,60,000
+   - Cr. TDS Payable ₹1,500 | Cr. Vendor AP ₹23,58,500
+
+SPREADSHEET COMPLIANCE FORMULAS
+--------------------------------------------------------------------------------
+1. TDS WITHHOLDING (Section 194Q):
+   • Standard Excel (Generic All-in-One):
+     =IF(AND(BuyerTurnoverCr > 10, TxnDate >= DATE(2021,7,1)), ROUND((MAX(0, (PriorSpend + IF(IsAdvance, GrossAmt, GrossAmt - GstAmt)) - 5000000) - MAX(0, PriorSpend - 5000000)) * IF(HasOperativePAN, 0.1%, 5.0%), -1), 0)
+
+   • Standard Excel (Case 01 Values):
+     =IF(AND(18.5 > 10, DATE(2025,5,1) >= DATE(2021,7,1)), ROUND((MAX(0, (4500000 + IF(FALSE, 2360000, 2360000 - 360000)) - 5000000) - MAX(0, 4500000 - 5000000)) * IF(TRUE, 0.1%, 5.0%), -1), 0)
+
+   • MudraForge Add-in:
+     =MF.TDS("194Q", 2360000, 4500000, TRUE, "2025-05-01", 18.5, 360000, FALSE)
+   -> Result        : ₹1,500.00
+
+2. STATUTORY DUE DATE (MSMED Act Section 15 & Section 43B(h)):
+   • Standard Excel : =DeliveryDate + MIN(AgreedContractDays, 45)
+   • MudraForge     : =MF.MSME.DUEDATE("2025-05-01", TRUE, "2025-06-30")
+   -> Result        : 15-June-2025