@mudraforge/statutory 2.8.1 → 2.10.0

package/bin/cli.js

@@ -22,6 +22,9 @@ import {
     runStatutoryDoctor,
     crosswalkStatute,
     getStatutoryDiff,
+    getStatutoryOutcomes,
+    explainStatutoryDisposition,
+    ignorePackageUpdate,
     STATUTORY_EXIT_CODES,
     STATUTORY_CLIENT_VERSION,
     DEFAULT_LOCAL_OKF_DIR
@@ -33,7 +36,14 @@ const __dirname = path.dirname(__filename);
 const rawArgs = process.argv.slice(2);
 const isJsonMode = rawArgs.includes('--json') || rawArgs.includes('-j');
 const isOfflineMode = rawArgs.includes('--offline') || rawArgs.includes('-o');
-const args = rawArgs.filter(a => a !== '--json' && a !== '-j' && a !== '--offline' && a !== '-o');
+const isVerboseMode = rawArgs.includes('--verbose') || rawArgs.includes('-v');
+const isNoUpdateCheck = rawArgs.includes('--no-update-check') || rawArgs.includes('--ignore-update');
+const args = rawArgs.filter(a => 
+    a !== '--json' && a !== '-j' && 
+    a !== '--offline' && a !== '-o' && 
+    a !== '--verbose' && a !== '-v' &&
+    a !== '--no-update-check' && a !== '--ignore-update'
+);
 const command = args[0] ? args[0].toLowerCase() : 'help';
 
 function getNamedArg(nameList, argList) {
@@ -89,6 +99,26 @@ async function main() {
             break;
         }
 
+        case 'outcomes':
+        case 'dispositions':
+        case 'states': {
+            const section = (args[1] && !args[1].startsWith('-')) ? args[1] : getNamedArg(['--provision', '-p', '--section', '-s'], rawArgs);
+            await handleOutcomes(section, { offline: isOfflineMode, verbose: isVerboseMode });
+            break;
+        }
+
+        case 'explain':
+        case 'why':
+        case 'remedy': {
+            const query = (args[1] && !args[1].startsWith('-')) ? args[1] : getNamedArg(['--code', '-c', '--query', '-q'], rawArgs);
+            if (!query) {
+                console.error('[ERROR] Please specify a disposition code or status to explain, e.g. npx @mudraforge/statutory explain BUYER_TURNOVER_UNVERIFIED');
+                process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+            }
+            await handleExplain(query);
+            break;
+        }
+
         case 'init-skill':
         case 'install-skill':
             await handleInitSkill(args[1]);
@@ -96,9 +126,11 @@ async function main() {
 
         case 'check-update':
         case 'status':
-        case 'version':
-            await handleCheckUpdate();
+        case 'version': {
+            const shouldIgnore = rawArgs.includes('--ignore') || args[1] === '--ignore' || args[1] === 'ignore';
+            await handleCheckUpdate({ ignore: shouldIgnore });
             break;
+        }
 
         case 'sync':
         case 'pull':
@@ -149,13 +181,14 @@ async function main() {
     }
 
     // Non-intrusive background npm package update notice
-    if (!isJsonMode && !['check-update', 'status', 'version', 'verify', 'audit', 'check', 'crosswalk', 'bridge', 'transition', 'diff', 'changelog', 'amendments'].includes(command)) {
+    if (!isJsonMode && !isNoUpdateCheck && command !== 'check-update' && command !== 'status' && command !== 'version') {
         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(`To dismiss: npx @mudraforge/statutory check-update --ignore`);
                 console.log('───────────────────────────────────────────────────────────────────────────\n');
             }
         } catch (_) {}
@@ -384,14 +417,182 @@ async function handleDiff(options) {
     }
 }
 
-async function handleCheckUpdate() {
+async function handleOutcomes(provision, options = {}) {
+    try {
+        const result = await getStatutoryOutcomes(provision, options);
+        if (isJsonMode) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(0);
+        }
+
+        console.log('\n===========================================================================');
+        console.log('MUDRAFORGE STATUTORY OUTCOMES & SEMANTIC DISPOSITION DICTIONARY');
+        console.log('===========================================================================');
+        console.log(`Source:              ${result.source} ${result.offlineFallback ? '(Offline Fallback)' : ''}`);
+        console.log(`Version:             v${result.version}`);
+        console.log(`Provision Filter:    ${result.provision || 'ALL (Global Catalog)'}`);
+        console.log(`Total Outcomes:      ${result.totalOutcomes}`);
+        console.log('===========================================================================');
+
+        if (result.outcomes.length === 0) {
+            console.log(`\nNo specific outcome codes mapped for provision "${result.provision}".`);
+            console.log('Showing all global disposition outcomes: run npx @mudraforge/statutory outcomes\n');
+        } else {
+            result.outcomes.forEach((o, idx) => {
+                console.log(`\n── Outcome #${idx + 1}: [${o.code}] ──`);
+                console.log(`Title:               ${o.title}`);
+                console.log(`Category:            ${o.category}`);
+                console.log(`Description:         ${o.description}`);
+                console.log(`Trigger Condition:   ${o.triggerCondition}`);
+                console.log(`Recommended Action:  ${o.recommendedAction}`);
+                if (options.verbose && o.remedy) {
+                    console.log(`Resolution Steps:    ${o.remedy}`);
+                }
+                if (o.missingFacts && o.missingFacts.length > 0) {
+                    console.log(`Missing Facts to Cure: ${o.missingFacts.join(', ')}`);
+                    if (options.verbose && o.missingFactsExplanation) {
+                        for (const [key, detail] of Object.entries(o.missingFactsExplanation)) {
+                            console.log(`  ↳ ${key} (${detail.type}): ${detail.description} (Source: ${detail.source})`);
+                        }
+                    }
+                }
+                if (options.verbose && o.consequenceIfUnresolved) {
+                    console.log(`Consequence on Hold: ${o.consequenceIfUnresolved}`);
+                }
+                if (o.applicableProvisions && o.applicableProvisions.length > 0) {
+                    console.log(`Applies to Sections: ${o.applicableProvisions.join(', ')}`);
+                }
+                console.log(`Governing Law:       ${o.governingAuthority}`);
+            });
+        }
+
+        console.log('\n───────────────────────────────────────────────────────────────────────────');
+        console.log(`[PASS] Statutory outcomes dictionary retrieved successfully (${result.totalOutcomes} outcome(s)) (Exit 0).\n`);
+        process.exit(0);
+    } catch (err) {
+        if (isJsonMode) {
+            console.log(JSON.stringify({ status: 'ERROR', exitCode: STATUTORY_EXIT_CODES.USAGE_ERROR, error: err.message }, null, 2));
+        } else {
+            console.error(`[ERROR] Statutory outcomes lookup failure: ${err.message}`);
+        }
+        process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+    }
+}
+
+async function handleExplain(query) {
+    try {
+        const result = explainStatutoryDisposition(query);
+        if (isJsonMode) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(0);
+        }
+
+        console.log('\n===========================================================================');
+        console.log(`MUDRAFORGE STATUTORY EXPLANATION: [${result.query}]`);
+        console.log('===========================================================================');
+
+        if (result.status === 'NOT_FOUND') {
+            console.log(`\nNo statutory disposition or indeterminate code found matching "${result.query}".`);
+            if (result.availableCodes && result.availableCodes.length > 0) {
+                console.log('\nAvailable disposition codes to inspect:');
+                result.availableCodes.forEach(c => console.log(`  • ${c}`));
+            }
+            console.log('\nTip: Run "npx @mudraforge/statutory explain INDETERMINATE" to view all hold states.\n');
+            process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+        }
+
+        if (result.summary) {
+            console.log(`Summary:             ${result.summary}`);
+            console.log(`Matched Dispositions: ${result.totalMatches}\n`);
+        }
+
+        result.matches.forEach((o, idx) => {
+            if (result.matches.length > 1) {
+                console.log(`\n── [${idx + 1}/${result.matches.length}] Disposition: [${o.code}] ──`);
+            } else {
+                console.log(`Code:                [${o.code}]`);
+            }
+            console.log(`Title:               ${o.title}`);
+            console.log(`Category:            ${o.category}`);
+            console.log(`Governing Law:       ${o.governingAuthority}`);
+            console.log('\n── What Happened:');
+            console.log(`  ${o.description}`);
+            console.log('\n── Statutory Trigger:');
+            console.log(`  ${o.triggerCondition}`);
+            console.log('\n── How to Resolve in Your Application:');
+            console.log(`  ${o.remedy || o.recommendedAction}`);
+
+            if (o.missingFacts && o.missingFacts.length > 0) {
+                console.log('\n── Missing Evidence / Parameters to Supply:');
+                o.missingFacts.forEach(f => {
+                    const meta = o.missingFactsExplanation ? o.missingFactsExplanation[f] : null;
+                    if (meta) {
+                        console.log(`  • ${f} (${meta.type}): ${meta.description}`);
+                        console.log(`    Source: ${meta.source} | Example: ${JSON.stringify(meta.example)}`);
+                    } else {
+                        console.log(`  • ${f}`);
+                    }
+                });
+            }
+
+            if (o.consequenceIfUnresolved) {
+                console.log('\n── Consequence If Unresolved:');
+                console.log(`  ${o.consequenceIfUnresolved}`);
+            }
+
+            if (o.applicableProvisions && o.applicableProvisions.length > 0) {
+                console.log(`\nApplies to Sections: ${o.applicableProvisions.join(', ')}`);
+            }
+        });
+
+        console.log('\n───────────────────────────────────────────────────────────────────────────');
+        console.log(`[PASS] Statutory explanation completed successfully (Exit 0).\n`);
+        process.exit(0);
+    } catch (err) {
+        if (isJsonMode) {
+            console.log(JSON.stringify({ status: 'ERROR', exitCode: STATUTORY_EXIT_CODES.USAGE_ERROR, error: err.message }, null, 2));
+        } else {
+            console.error(`[ERROR] Statutory explain failure: ${err.message}`);
+        }
+        process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+    }
+}
+
+async function handleCheckUpdate(options = {}) {
     try {
         let pkgUpdate = null;
         try {
-            pkgUpdate = await checkForPackageUpdate({ cacheTtlMs: 0 });
+            pkgUpdate = await checkForPackageUpdate({ cacheTtlMs: 0, force: Boolean(options.ignore) });
         } catch (_) {}
 
-        const status = await checkUpdates();
+        if (options.ignore) {
+            const versionToIgnore = pkgUpdate?.latestVersion || STATUTORY_CLIENT_VERSION;
+            ignorePackageUpdate(versionToIgnore);
+            if (isJsonMode) {
+                console.log(JSON.stringify({ status: 'SUCCESS', ignoredVersion: versionToIgnore }, null, 2));
+                process.exit(0);
+            }
+            console.log('\n===========================================================================');
+            console.log(`[OK] Update notifications will be ignored for version ${versionToIgnore}.`);
+            console.log('You will not see update notices until a newer version is published.');
+            console.log('===========================================================================\n');
+            process.exit(0);
+        }
+
+        let status = null;
+        try {
+            status = await checkUpdates();
+        } catch (netErr) {
+            if (isJsonMode) {
+                console.log(JSON.stringify({ status: 'OFFLINE_FALLBACK', packageUpdate: pkgUpdate, error: netErr.message }, null, 2));
+                process.exit(0);
+            }
+            console.log('───────────────────────────────────────────────────────────────────────────');
+            console.log(`Local OKF Version:   ${STATUTORY_CLIENT_VERSION}`);
+            console.log(`Edge Synchronization: UNAVAILABLE (offline or remote network unreachable)`);
+            console.log('───────────────────────────────────────────────────────────────────────────\n');
+            process.exit(0);
+        }
 
         if (isJsonMode) {
             console.log(JSON.stringify({
@@ -710,10 +911,12 @@ Commands:
   verify [path]             Cryptographically verify OKF substrate authenticity & file integrity
   crosswalk <section>       Dual-act 1961 <-> 2025 bridge (earlier of credit vs payment)
   diff                      Semantic regulatory changelog (--section, --since, --domain)
+  outcomes [provision]      Inspect API dispositions, statutory states, trigger conditions & actions
+  explain <code/status>     In-depth explanation, legal rationale & remediation steps for a disposition
   browse                    Interactively browse local OKF statutory filesystem
   lookup <section> [date]   Look up section details & temporal status (e.g. 194Q 2025-06-01)
   decode-id <pan_or_gstin>  Offline ISO Mod-36 checksum, state name, and PAN entity decoding
-  check-update              Check if newer OKF versions or legal changes exist on Cloudflare edge
+  check-update [--ignore]   Check edge updates; pass --ignore to snooze notices for current version
   sync [path]               Download/sync latest versioned OKF bundle to disk (default: package okf/ or custom dir)
   list                      List all indexed statutory sections
   init-skill [path]         Install SKILL.md into your agent workspace (defaults to .agents/skills/)
@@ -725,6 +928,10 @@ Options:
   --since <YYYY-MM-DD>      Filter amendments taking effect on or after date (used in diff)
   --section, -s <section>   Filter amendments by section code (used in diff)
   --domain <domain>         Filter amendments by statutory domain (used in diff)
+  --verbose, -v             Display full remediation steps, parameter schemas, and consequences in outcomes
+  --no-update-check         Bypass automated background npm package update checks
+  --json, -j                Emit clean, machine-parseable JSON to stdout (suppresses banners)
+  --offline, -o             Bypass outbound network checks (air-gapped / offline environment mode)
   --json, -j                Emit clean, machine-parseable JSON to stdout (suppresses banners)
   --offline, -o             Bypass outbound network checks (air-gapped / offline environment mode)
 

package/calculators.d.ts

@@ -0,0 +1 @@
+export * from './types/index.js';

package/calculators.js

@@ -0,0 +1 @@
+export * from './src/calculators.js';

package/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # MudraForge Statutory Architecture
 ## Grounding Financial AI in Deterministic Law & Open Knowledge
 
-> **MudraForge Statutory Bundle**: `v2.4.0`  
+> **MudraForge Statutory Bundle**: `v2.9.0`  
 > **Knowledge Specification**: Google Open Knowledge Format (OKF) specification (upstream v0.2)  
 > **License**: MIT (Public Knowledge Commons)  
 > **Status**: Public Beta  
@@ -592,10 +592,10 @@ Data traveling between tiers is encapsulated within a deterministic verification
 
 ```json
 {
-  "protocolVersion": "okf/2.4.0",
+  "protocolVersion": "okf/2.9.0",
   "domain": "direct_tax",
   "sectionCode": "194Q",
-  "manifestDigest": "sha256-d9612074241f7c2cc1d05fa5eee254996f21db56ad1ab71ac36a084ffd4169e1",
+  "manifestDigest": "sha256-4bbe36c3db841b833dd2bebbd6c1c5ed735498e7b20d1221c323ceb211529fe0",
   "effectiveTemporalStatus": "ACTIVE",
   "canonicalParameters": {
     "standardRatePercent": 0.1,
@@ -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.4.0:...`).
-2. *Atomic Manifest Flip*: The global pointer `statutory:active_release` is updated only after all 25+ files across all domains are fully confirmed across edge replicas.
-3. *Cache-Control Invalidation*: Manifest responses carry strict validation headers (`ETag: "v2.4.0"`, `stale-while-revalidate=600`).
+1. *Immutable Version Tagging*: All statutory releases are written under unique semver namespaces (`statutory:releases:v2.9.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`).
 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.4.0:direct_tax:194Q
+   # Example: statutory:releases:v2.9.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.4.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.9.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.
 

package/docs/ARCHITECTURE_DECISIONS.md

@@ -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.4.0` |
+| **`version`** (SemVer) | NPM Client SDK & CLI | Standard Semantic Versioning for the JavaScript library, CLI commands, and test runners. | `2.9.0` |
 
 ---
 
@@ -82,14 +82,15 @@ To maintain institutional credibility, public documentation must never blur the
 
 | Subsystem / Capability | Architectural Layer | Operational Status | Availability / Access | Verification Evidence |
 | :--- | :--- | :--- | :--- | :--- |
-| **Bundled OKF Statutory Corpus (11 Provisions)** | Layer 1: Public Package | `PUBLIC_BUNDLED` | Immediate (Local repo & release candidate) | 40/40 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) | 80/80 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 |
 | **Synthetic AP Execution Trace (`examples/`)** | Layer 1: Public Package | `PUBLIC_DEMO_SYNTHETIC` | Immediate (`npm run example:trace`) | Modeled 7-stage lifecycle with synthetic test fixtures |
 | **Cloudflare Anycast Edge Sync** | Layer 2: Public Edge Service | `PUBLIC_EDGE_SYNC` | Free Beta (`api.mudraforge.in`) | Cloudflare Edge Worker manifest & bundle endpoints |
 | **Interactive API Documentation** | Layer 2: Public Edge Service | `PUBLIC_EDGE_SYNC` | Free Beta (`/api/v1/statutory/docs`) | OpenAPI 3.1 schema rendered live on Anycast edge |
-| **Deterministic Tax Calculators** | Layer 3: Enterprise Internal | `PILOT_STAGE_INTERNAL` | Metered Enterprise API (Selective) | Deterministic arithmetic engine under test harness |
+| **Deterministic Calculators (7 Pure Functions)** | Layer 1: Public Package | `PUBLIC_BUNDLED` | Immediate (`@mudraforge/statutory/calculators`) | Corporate tax MAT vs concessional, GST POS/LUT, TP ALP, Section 79, Ind AS 109, Section 288B |
+| **Hosted AP Engine & Cumulative Spend Tracking** | Layer 3: Enterprise Internal | `PILOT_STAGE_INTERNAL` | Metered Enterprise API (Selective) | Hosted cumulative Section 194Q thresholding & Section 16 MSMED interest |
 | **Dual-Custody Mobile Approval Harness** | Layer 4: Adesha Runtime | `INTERNAL_PROTOTYPE` | Enterprise License / Pilot Proposal | Mobile passkey approval prototype & TLA+ state machine |
 | **ERP Two-Way Connectors (SAP/Tally/Zoho)** | Layer 4: Adesha Runtime | `INTERNAL_DEVELOPMENT` | Custom Enterprise Pilot | Shadow-mode test connectors; no turnkey plug-ins shipped |
 | **Bank Rail API Adapters (ICICI/HDFC/RazorpayX)**| Layer 4: Adesha Runtime | `INTERNAL_DEVELOPMENT` | Custom Enterprise Pilot | Sandbox banking adapters requiring corporate partner onboarding |