@mudraforge/statutory 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.4.2] - 2026-10-24
+
+### Added
+- **npm Package Update Notifier**: Lightweight, zero-dependency update notifier querying `registry.npmjs.org` with a 24-hour temporary file cache (`checkForPackageUpdate()`).
+- **Unified `check-update` CLI Command**: Now audits both npm package code updates against the npm registry and legal rule updates against the Cloudflare Edge manifest.
+- **Non-Intrusive Terminal Footers**: Automatically surfaces `[NOTICE]` prompts when a newer npm release is available, with opt-out support via `NO_UPDATE_NOTIFIER=1` or `CI=true`.
+
+---
+
+## [2.4.1] - 2026-10-24
+
+### Added
+- **Developer Navigation & Usability**: Compact, audited Table of Contents in `README.md` targeting all key documentation sections.
+- **Package Metadata**: Official `homepage` pointing to `https://mudraforge.in/docs` and `bugs` pointing to GitHub Issues.
+- **Supported Application Patterns**: Documented clear integration boundaries across AI Agents (local `SKILL.md`), Finance Software (declarative threshold schemas), and Developer Tooling.
+- **Corporate M&A Restructuring Domain**: Section 50B slump sale capital gains based on WDV net worth (Section 43(6)), Form 3CEA CA certification schema, and Section 281 clearance checklist.
+- **Dual-Act Successor Mapping**: Section 393 (*Income-tax Act, 2025*) successor provision mapping for Section 194Q.
+- **Cryptographic Trust Anchor & Anti-Tamper Hardening**: Ed25519 digital signature verification for remote bundles, CRL key revocation enforcement, replay protections, Windows reserved device name protection, and strict production bypass locks (36 passing regression suites).
+
+### Changed
+- **Statutory Rate Enforcements**: Section 194J non-PAN deduction rate updated to the statutory 20% penalty tier under Section 206AA.
+- **Quotas & Error Semantics**: Documented Cloudflare Edge API rate limits, error codes, and HTTP semantics.
+
+---
+
 ## [2.4.0] - 2026-10-22
 
 ### Added

package/README.md

@@ -15,7 +15,7 @@
 
 | Item | Value |
 |---|---|
-| **Package Release** | **`v2.4.0`** (Public Beta) |
+| **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) |
@@ -31,6 +31,46 @@
 
 ---
 
+## Table of Contents
+
+- [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)
+  - [3. Direct Programmatic Traversal](#3-direct-programmatic-traversal-zero-dependencies-offline-first)
+- [Supported Application Patterns](#supported-application-patterns)
+  - [1. AI Agents & LLM Tooling](#1-ai-agents--llm-tooling)
+  - [2. Finance Software & Accounts-Payable Workflows](#2-finance-software--accounts-payable-workflows)
+  - [3. Developer Tooling & Audit Verification](#3-developer-tooling--audit-verification)
+- [Tier Separation: Free Commons vs. Hosted Calculation Engine](#architectural-boundaries-open-substrate-vs-hosted-edge-vs-adesha-platform)
+- [Legal Domains Currently Covered](#legal-domains-currently-covered)
+- [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)
+  - [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)
+
+---
+
+## Supported Application Patterns
+
+`@mudraforge/statutory` serves as an authoritative reference layer and computation client across three distinct environments:
+
+### 1. AI Agents & LLM Tooling
+- **Current Implementation**: Generates a self-contained [`SKILL.md`](./SKILL.md) skill definition (`npx @mudraforge/statutory init-skill`) that connects agent runtimes directly to the local filesystem without external API calls or token bloat from search queries.
+- **Integration Boundary**: Agents can read structured section definitions (`okf/**/section.json`) to discover rates, thresholds, and return filing schemas deterministically rather than relying on model parameter memory.
+
+### 2. Finance Software & Accounts-Payable Workflows
+- **Current Implementation**: Provides offline threshold logic (such as Section 194Q cumulative purchases exceeding ₹50 Lakhs) and legislative sunsets (Section 206C(1H) omission on 1 April 2025). The hosted enterprise tier provides deterministic calculation via `client.calculate()`.
+- **Integration Boundary**: Custom accounting engines or enterprise middleware can invoke these functions via Node.js or REST endpoints. *(Note: This package exposes standard programmatic and JSON interfaces; it does not ship pre-packaged ERP plugins for third-party platforms).*
+
+### 3. Developer Tooling & Audit Verification
+- **Current Implementation**: CLI commands (`browse`, `lookup`, `list`, `check-update`) allow developers and tax compliance teams to inspect verified primary citations, download statutory checklists (such as Form 3CEA slump sale audit requirements), and verify dual-act forward crosswalks between the 1961 and 2025 Income-tax Acts.
+- **Integration Boundary**: Usable standalone in terminal environments, continuous integration (CI) compliance checks, or custom tax tooling.
+
+---
+
 ## The Payment Instruction Boundary & End-to-End AP Architecture
 
 > **The Dangerous Moment in Finance AI**:  

package/bin/cli.js

@@ -16,6 +16,8 @@ import {
     checkUpdates,
     syncOkf,
     getLocalManifest,
+    checkForPackageUpdate,
+    STATUTORY_CLIENT_VERSION,
     DEFAULT_LOCAL_OKF_DIR
 } from '../src/index.js';
 
@@ -68,10 +70,36 @@ async function main() {
             printHelp();
             break;
     }
+
+    // Non-intrusive background npm package update notice
+    if (!['check-update', 'status', 'version'].includes(command)) {
+        try {
+            const updateInfo = await checkForPackageUpdate();
+            if (updateInfo && updateInfo.updateAvailable) {
+                console.log('───────────────────────────────────────────────────────────────────────────');
+                console.log(`[NOTICE] A new version of @mudraforge/statutory is available: ${updateInfo.currentVersion} -> ${updateInfo.latestVersion}`);
+                console.log(`Run: npm install @mudraforge/statutory@latest or npx @mudraforge/statutory@latest`);
+                console.log('───────────────────────────────────────────────────────────────────────────\n');
+            }
+        } catch (_) {}
+    }
 }
 
 async function handleCheckUpdate() {
     try {
+        console.log('\n[INFO] Checking npm package version against registry.npmjs.org...');
+        try {
+            const pkgUpdate = await checkForPackageUpdate({ cacheTtlMs: 0 });
+            if (pkgUpdate && pkgUpdate.updateAvailable) {
+                console.log('───────────────────────────────────────────────────────────────────────────');
+                console.log(`[WARN] New npm package version available: v${pkgUpdate.latestVersion} (installed: v${pkgUpdate.currentVersion})`);
+                console.log(`Run: npm install @mudraforge/statutory@latest`);
+                console.log('───────────────────────────────────────────────────────────────────────────');
+            } else if (pkgUpdate) {
+                console.log(`[OK] npm package code is up to date (v${pkgUpdate.currentVersion}).`);
+            }
+        } catch (_) {}
+
         console.log('\n[INFO] Checking OKF knowledge substrate status against Cloudflare edge...');
         const status = await checkUpdates();
         console.log('───────────────────────────────────────────────────────────────────────────');
@@ -82,7 +110,7 @@ async function handleCheckUpdate() {
         console.log('───────────────────────────────────────────────────────────────────────────');
 
         if (status.isOutdated) {
-            console.log(`[WARN] New version available: v${status.latestVersion}`);
+            console.log(`[WARN] New legal data version available: v${status.latestVersion}`);
             console.log(`Changelog: ${status.changelog}`);
             console.log(`Run: npx @mudraforge/statutory sync to pull the latest rules.\n`);
         } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mudraforge/statutory",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "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",
@@ -38,6 +38,10 @@
     "type": "git",
     "url": "https://github.com/mondeep0123/mudraforge-statutory.git"
   },
+  "homepage": "https://mudraforge.in/docs",
+  "bugs": {
+    "url": "https://github.com/mondeep0123/mudraforge-statutory/issues"
+  },
   "keywords": [
     "tax",
     "india",

package/src/index.js

@@ -10,6 +10,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
@@ -17,7 +18,7 @@ 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.0';
+export const STATUTORY_CLIENT_VERSION = '2.4.2';
 
 /**
  * Pinned official release Merkle root digests.
@@ -430,6 +431,78 @@ export async function checkUpdates(options = {}) {
     };
 }
 
+/**
+ * Check if a newer version of the @mudraforge/statutory npm package is published on npmjs.com.
+ * Uses a lightweight cached file in os.tmpdir() to prevent frequent network roundtrips.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.currentVersion] - Current installed version (defaults to STATUTORY_CLIENT_VERSION).
+ * @param {number} [options.cacheTtlMs] - Cache duration in milliseconds (default: 24 hours).
+ * @param {number} [options.timeoutMs] - Request timeout in milliseconds (default: 1500ms).
+ * @param {string} [options.registryUrl] - Registry endpoint (default: https://registry.npmjs.org/@mudraforge/statutory/latest).
+ * @returns {Promise<{ updateAvailable: boolean, currentVersion: string, latestVersion: string } | null>}
+ */
+export async function checkForPackageUpdate(options = {}) {
+    if (process.env.NO_UPDATE_NOTIFIER === '1' || process.env.CI === 'true') {
+        return null;
+    }
+
+    const currentVersion = options.currentVersion || STATUTORY_CLIENT_VERSION;
+    const cacheTtlMs = options.cacheTtlMs !== undefined ? options.cacheTtlMs : 24 * 60 * 60 * 1000;
+    const timeoutMs = options.timeoutMs || 1500;
+    const cacheFile = path.join(os.tmpdir(), '.mudraforge_statutory_npm_update.json');
+
+    let cached = null;
+    if (cacheTtlMs > 0) {
+        try {
+            if (fs.existsSync(cacheFile)) {
+                const data = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+                if (data && typeof data.lastChecked === 'number' && (Date.now() - data.lastChecked < cacheTtlMs)) {
+                    cached = data;
+                }
+            }
+        } catch (_) {}
+    }
+
+    let latestVersion = cached?.latestVersion;
+
+    if (!latestVersion) {
+        try {
+            const url = options.registryUrl || 'https://registry.npmjs.org/@mudraforge/statutory/latest';
+            const res = await fetch(url, {
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { 'Accept': 'application/json' }
+            });
+            if (res.ok) {
+                const json = await res.json();
+                if (json && json.version && typeof json.version === 'string') {
+                    latestVersion = json.version;
+                    if (cacheTtlMs > 0) {
+                        try {
+                            fs.writeFileSync(cacheFile, JSON.stringify({
+                                lastChecked: Date.now(),
+                                latestVersion
+                            }), 'utf8');
+                        } catch (_) {}
+                    }
+                }
+            }
+        } catch (_) {
+            // Fail open and silent on network error, offline, or timeout
+            return null;
+        }
+    }
+
+    if (!latestVersion) return null;
+
+    const cmp = compareSemver(latestVersion, currentVersion);
+    return {
+        updateAvailable: cmp > 0,
+        currentVersion,
+        latestVersion
+    };
+}
+
 /**
  * Download and synchronize the latest OKF knowledge bundle to disk.
  * Hardened with:

package/types/index.d.ts

@@ -148,6 +148,12 @@ export declare function getLocalManifest(okfDir?: string): any;
 export declare function lookupLocalStatute(section: string, okfDir?: string): StatutoryRecord | null;
 export declare function computeTemporalStatus(statute: StatutoryRecord, asOfDate?: string): 'ACTIVE' | 'SUNSET_SUPERSEDED' | 'FUTURE_PENDING';
 export declare function checkUpdates(options?: { baseUrl?: string; okfDir?: string }): Promise<UpdateInfo>;
+export declare function checkForPackageUpdate(options?: {
+    currentVersion?: string;
+    cacheTtlMs?: number;
+    timeoutMs?: number;
+    registryUrl?: string;
+}): Promise<{ updateAvailable: boolean; currentVersion: string; latestVersion: string } | null>;
 export declare function syncOkf(options?: { baseUrl?: string; okfDir?: string }): Promise<SyncResult>;
 
 export declare function lookupStatute(