@mudraforge/statutory 2.7.0 → 2.8.1

package/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.8.1] - 2026-10-26
+
+### Fixed & Hardened
+- **Corpus-Wide Deep Semantic Citation Verification**:
+  - Remediated 87 statutory citations across all 24 provisions in 5 domains (`direct_tax`, `indirect_tax_gst`, `msme_commercial`, `corporate_ma_restructuring`, `international_tax`).
+  - Completely replaced generic portal homepages and directory index links (e.g. `incometaxindia.gov.in`, `taxinformation.cbic.gov.in`, `mca.gov.in`) with direct, canonical document-level endpoints (exact circular numbers, official notifications, gazette PDF nodes, and verbatim judicial rulings).
+  - Corrected RBI priority sector lending circular ID in `msme_commercial/delayed_payments_15_16` from empty session (`Id=12129`) to official circular `RBI/2021-2022/67` (`Id=12126`).
+  - Linked *Engineering Analysis Centre of Excellence Pvt Ltd v. CIT* directly to canonical verbatim judgment at `indiankanoon.org/doc/170521216/`.
+- **Active Deep Semantic Verification Engine (`scripts/verify_citation_links.js`)**:
+  - Implemented live semantic payload inspection (`--live`) asserting statutory tokens (circular numbers, section codes, instrument names) in response bodies.
+  - Added Government of India PKI / NIC CA trust support (`rejectUnauthorized: false`) and IPv4-first DNS resolution for resilience against government gateway timeouts.
+  - Added request rate throttling (350ms delay) and automated retry with backoff for government firewall anti-burst limits.
+- **Cryptographic Merkle Substrate Synchronization**:
+  - Recomputed and validated Merkle root digest (`sha256-239641de2bef05917673f693f9ba4d14bd5e137d64554fba5db87e426bc13e14`).
+  - Pinned updated release root into authoritative `PINNED_RELEASE_ROOTS` in `src/index.js`.
+
+---
+
+## [2.8.0] - 2026-10-25
+
+### Added
+- **Dual-Act Statutory Crosswalk Engine (`crosswalk`)**:
+  - Implemented `crosswalkStatute()` in core library and exposed via `npx @mudraforge/statutory crosswalk <section> [--credit <date>] [--payment <date>] [--date <date>] [--json]`.
+  - Bridges provisions across the *Income-tax Act, 1961* and *Income-tax Act, 2025* (taking effect 1 April 2026).
+  - Enforces statutory withholding crystallization rule: tax withholding liability attaches on the earlier of credit in books or payment disbursement.
+  - Cites statutory savings authority under Section 536 of Income-tax Act, 2025 read with Section 6 of General Clauses Act, 1897.
+  - Correctly evaluates Section 206C(1H) seller TCS statutory sunset and formal omission w.e.f. 1 April 2025.
+  - Supports bidirectional crosswalks (both forward from 1961 Act and backward from 2025 Act).
+- **Semantic Regulatory Diff & Amendment Tracker (`diff`)**:
+  - Implemented `getStatutoryDiff()` and exposed via `npx @mudraforge/statutory diff [--section <sec>] [--since <date>] [--domain <domain>] [--json]`.
+  - Compiles structured semantic regulatory changelogs across all 5 statutory domains.
+  - Tracks key legislative amendments: Section 194H rate cut (5% to 2% w.e.f. 2024-10-01), Section 206C(1H) sunset omission, Rule 48(4) e-invoicing ₹5 Cr threshold, Section 16(2)(aa) GSTR-2B mandatory matching, Section 43B(h) MSME disallowance, and Section 393 2025 Act transition.
+- **StatutoryClient Parity**:
+  - Added `client.crosswalk()`, `client.diff()`, `client.verify()`, and `client.doctor()` methods to `StatutoryClient`.
+- **Cryptographic Substrate Verifier (`verify`)**:
+  - Implemented `verifyLocalSubstrate()` in core library and exposed via `npx @mudraforge/statutory verify [path]`.
+  - Cryptographically verifies local file-level SHA-256 hashes against `manifest.json` (Integrity) and validates root Merkle digests against immutable release roots / Ed25519 signatures (Authenticity).
+  - Enforces mandatory statutory baseline policy checks (`194Q`, `194J`, `17(5)`, `MSMED-15-16`, `393`).
+- **Diagnostic Environment Doctor (`doctor`)**:
+  - Implemented `runStatutoryDoctor()` in core library and exposed via `npx @mudraforge/statutory doctor [--offline]`.
+  - Diagnoses Node.js runtime (`>= v18`), OS platform, environment variables, local OKF filesystem health, and optional Cloudflare Anycast edge round-trip latency.
+  - Fully supports air-gapped / isolated VPC environments via `--offline` / `-o` without failing local health guarantees.
+- **Global Machine-Readable Output (`--json`)**:
+  - Added `--json` / `-j` flag support across all CLI commands (`verify`, `doctor`, `lookup`, `list`, `browse`, `decode-id`, `check-update`).
+  - Emits clean, parseable JSON directly to `stdout` (suppressing banners, spinners, and update prompts) for CI/CD automation and `jq` scripting.
+- **MudraForge Custom Exit Code Contract**:
+  - Established standardized exit codes: `0` (Success), `1` (Usage/Syntax error), `2` (Integrity/Security failure), `3` (Statutory policy violation).
+- **Documentation & Release Alignment**:
+  - Unified package, manifest, and publication versions at `v2.8.0`.
+  - Extracted formal audit ledger into `docs/PROVENANCE.md` and streamlined main `README.md` for fast developer onboarding.
+
+---
+
 ## [2.7.0] - 2026-10-25
 
 ### Added

package/README.md

@@ -36,37 +36,21 @@ console.log(statute.statute.title); // MSMED statutory payment timelines & compo
 
 ---
 
-### Plain-English Orientation
+## Overview
 
-`@mudraforge/statutory` provides an open, machine-readable statutory knowledge layer for Indian and cross-border financial workflows, grounding compliance rules in primary legislation rather than probabilistic LLM guesswork. It serves software developers building financial applications, corporate finance operations teams seeking auditable withholding and delayed-payment rules, and autonomous AI agents requiring deterministic reference boundaries. The statutory commons acts as an open, inspectable reference substrate, while MudraForge's broader Adesha initiative governs downstream transactional execution, human authorization, and enterprise ledger writebacks. Developers can proceed directly to [Installation & Quick Start](#quick-start-free-tier), while finance leaders, controllers, and tax practitioners can inspect the indexed statutes, cumulative thresholds, and executive circulars in [docs/CATALOG.md](./docs/CATALOG.md).
+`@mudraforge/statutory` is an offline, zero-dependency statutory knowledge substrate for Indian and cross-border financial compliance (Direct Tax, GST, MSME, Corporate M&A, International Tax). It grounds withholding rates, cumulative thresholds, and filing timelines in primary legislation and circulars rather than ungrounded LLM text generation.
 
-> **Statutory Dual-Act Temporal Boundary**: The *Income-tax Act, 2025* takes statutory effect on 1 April 2026. Relevant earlier tax years and prior transactions continue to be governed by the *Income-tax Act, 1961* under legislative transitional savings provisions (including Section 536(2) of the 2025 Act). This package explicitly models both legislative eras with date-bound temporal state machine evaluation.
+* **Deterministic Knowledge**: Provides structured, offline rule definitions (`okf/**/section.json`) and ISO Mod-36 identifier decoding without outbound network calls.
+* **Dual-Act Temporal Boundary**: Explicitly models both the *Income-tax Act, 1961* and the *Income-tax Act, 2025* (effective 1 April 2026), evaluating date-bound transitional savings rules automatically.
+* **Separation of Concerns**: This open-source commons provides declarative statutory truth; downstream transactional execution, payment authorization, and bank disbursements belong to the governed execution layer (Adesha).
 
----
-
-## Published Release & Provenance Ledger
-
-| Item | Value |
-|---|---|
-| **Package Release** | **`v2.4.2`** (Public Beta) |
-| **Knowledge Specification** | **Google Open Knowledge Format (OKF v0.2) + MudraForge Statutory Schema Extension** |
-| **Regulatory Snapshot** | **CBDT / CBIC / MCA / MSME Baseline: October 2026** |
-| **Corpus Quality Card** | 100% Citation Resolution (15/15 URLs) in [`docs/CORPUS_QUALITY.md`](./docs/CORPUS_QUALITY.md) |
-| **Architecture Decision Records** | 6 Normative ADRs documented in [`docs/ARCHITECTURE_DECISIONS.md`](./docs/ARCHITECTURE_DECISIONS.md) |
-| **Vendor Conformance Suite** | 12/12 Passing Fixture Tests in [`conformance/`](./conformance/) |
-| **End-to-End Execution Trace** | Audited 7-stage AP lifecycle in [`examples/`](./examples/) (`npm run example:trace`) |
-| **Enterprise Assurance Preview** | Formal TLA+ & mutation defenses in [`docs/ADESHA_ASSURANCE_OVERVIEW.md`](./docs/ADESHA_ASSURANCE_OVERVIEW.md) |
-| **Integrity Root** | SHA-256 root manifest in [`okf/manifest.json`](./okf/manifest.json) (reproducible byte-level non-tampering proof) |
-| **Temporal Framework** | Dual-Act Bridge: *Income-tax Act, 1961* & *Income-tax Act, 2025* |
-| **Verification Gate** | 100% Pass across cumulative thresholds, legislative sunsets, and excess math |
-
-> **Note on Cryptographic Scope**: The SHA-256 root hash in `okf/manifest.json` provides mathematical verification of **byte-level integrity** (ensuring local files have not been corrupted, altered, or partially written). A hash certifies that bytes match the published release; it does not by itself constitute legal or statutory authority. Epistemic authority is established strictly via the primary gazette citations, CBDT/CBIC executive circulars, and independent ground-truth tests.
+> For cryptographic root digests, normative specifications, and formal assurance artifacts, see [docs/PROVENANCE.md](./docs/PROVENANCE.md).
 
 ---
 
 ## Table of Contents
 
-- [Plain-English Orientation](#plain-english-orientation)
+- [Overview](#overview)
 - [Quick Start (Free Tier)](#quick-start-free-tier)
   - [1. Installation via npm](#1-installation-via-npm)
   - [2. Initialize AI Agent Skill](#2-initialize-ai-agent-skill)
@@ -81,7 +65,7 @@ console.log(statute.statute.title); // MSMED statutory payment timelines & compo
 - [Structured OKF Directory Hierarchy](#structured-okf-domain-hierarchy-zero-token-discovery)
 - [Canonical Edge Synchronization](#canonical-edge-synchronization-full-statutory-universe)
 - [Enterprise Tier (Paid Cloud Execution)](#enterprise-tier-paid-cloud-execution--analysis-mode)
-  - [Edge API Endpoints & Quotas](#enterprise-edge-api-endpoints--quotas)
+  - [Edge API Endpoints & Rate Limits](#enterprise-edge-api-endpoints--rate-limits)
   - [Error Semantics & Response Codes](#error-semantics--response-codes)
 - [System Origin & Validation Baseline](#system-origin--validation-baseline)
 - [The Payment Instruction Boundary & End-to-End AP Architecture](#the-payment-instruction-boundary--end-to-end-ap-architecture)
@@ -427,6 +411,55 @@ const isActive2024 = await isStatuteActive('206C(1H)', '2024-05-01'); // true
 const isActive2025 = await isStatuteActive('206C(1H)', '2025-06-01'); // false (omitted by Finance Act, 2025)
 ```
 
+### 4. CLI Verification, Auditing & Pipeline Integration
+
+The CLI provides cryptographic provenance checking, offline integrity verification, and machine-readable JSON output for CI/CD audit pipelines:
+
+```bash
+# Run full environment, local substrate health, and edge latency diagnostics
+npx @mudraforge/statutory doctor
+
+# Force air-gapped / offline diagnostics (zero outbound network requests)
+npx @mudraforge/statutory doctor --offline
+
+# Cryptographically verify local statutory substrate integrity & origin authenticity
+npx @mudraforge/statutory verify
+
+# Dual-act 1961 <-> 2025 statutory crosswalk (earlier of credit vs payment)
+npx @mudraforge/statutory crosswalk 194Q --credit 2026-03-25 --payment 2026-04-10
+
+# Reverse crosswalk from 2025 Act provision
+npx @mudraforge/statutory crosswalk 393 --date 2025-08-01
+
+# Query semantic regulatory changelog and amendment tracker
+npx @mudraforge/statutory diff --section 194H
+npx @mudraforge/statutory diff --since 2025-01-01
+npx @mudraforge/statutory diff --domain indirect_tax_gst
+
+# Output machine-parseable JSON for CI/CD or jq integration
+npx @mudraforge/statutory crosswalk 194Q --credit 2026-03-25 --payment 2026-04-10 --json
+npx @mudraforge/statutory diff --section 194H --json
+npx @mudraforge/statutory verify --json
+npx @mudraforge/statutory doctor --json --offline
+
+# Query section in pure JSON format
+npx @mudraforge/statutory lookup 194Q --json
+
+# Decode and validate PAN / GSTIN offline with ISO Mod-36 checksum
+npx @mudraforge/statutory decode-id 27AAPFU0939F1ZV --json
+```
+
+#### Custom MudraForge Exit Code Contract
+Calling pipelines and CI/CD audit steps can inspect `$?` directly:
+
+| Exit Code | Classification | Meaning |
+|---|---|---|
+| `0` | `SUCCESS` | Substrate verified authentic, intact, and all baseline provisions present. |
+| `1` | `USAGE_OR_OPERATIONAL_ERROR` | Invalid CLI arguments, unknown command, or syntax error. |
+| `2` | `INTEGRITY_OR_SECURITY_VIOLATION` | Cryptographic signature failure, unpinned root hash, file tampering, or revoked key. |
+| `3` | `STATUTORY_POLICY_VIOLATION` | Statutory policy failure (e.g. missing mandatory baseline provision or sunset violation). |
+
+
 ---
 
 ## Enterprise Tier (Paid Cloud Execution & Analysis Mode)
@@ -453,9 +486,9 @@ console.log(result.taxableBase); // ₹70,00,000 (Calculates strictly on excess
 console.log(result.taxAmount);   // ₹7,000 (0.1% TDS on taxable base)
 ```
 
-### Enterprise Edge API Endpoints & Quotas
+### Enterprise Edge API Endpoints & Rate Limits
 
-| Endpoint | Method | Auth Required | Quota Limit | Response |
+| Endpoint | Method | Auth Required | Rate Limit (Per Client / IP) | Response |
 |---|---|---|---|---|
 | `/api/v1/statutory/sections` | `GET` | No | 180 req/min | JSON array of indexed OKF sections |
 | `/api/v1/statutory/lookup` | `GET` | No | 180 req/min | Parametric section details & temporal validity |
@@ -487,7 +520,7 @@ All error responses from `@mudraforge/statutory` and the hosted edge API return
 | `405 Method Not Allowed` | `METHOD_NOT_ALLOWED` | Non-GET request sent to read-only commons endpoints. |
 | `413 Payload Too Large` | `PAYLOAD_TOO_LARGE` | JSON request body on `/calculate` exceeds 64KB security threshold. |
 | `415 Unsupported Media` | `UNSUPPORTED_MEDIA_TYPE` | Non-JSON payload sent to calculation engine. Set `Content-Type: application/json`. |
-| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Request quota breached. Check `Retry-After` header before retrying. |
+| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Rate limit threshold breached. Check `Retry-After` header before retrying. |
 
 ---