@mudraforge/statutory 2.9.0 → 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/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 |

package/docs/CATALOG.md

@@ -1,7 +1,7 @@
 # Statutory Knowledge Catalog
 
 > **Institutional Reference Index**  
-> Package: `@mudraforge/statutory` | Version: `2.4.0` | Standard: `OKF v0.2`  
+> Package: `@mudraforge/statutory` | Version: `2.10.0` | Standard: `OKF v0.2`  
 > Epistemic Baseline: Union Budget 2025-26, Finance Act, 2025, and official executive gazettes.
 
 This catalog is deterministically generated from the machine-readable Open Knowledge Format (`section.json`, executive circulars, and return schemas) bundled within this repository.

package/docs/CORPUS_QUALITY.md

@@ -1,9 +1,9 @@
 # MudraForge Statutory Knowledge Quality Card
 
 > **Format Reference**: Inspired by Google's *Data Cards Playbook* and the OpenSSF Project Quality Standards.  
-> **Target Package**: `@mudraforge/statutory` v2.4.0  
+> **Target Package**: `@mudraforge/statutory` v2.10.0  
 > **Evaluation Mode**: Machine-audited against primary sources, official gazettes, and test fixtures.  
-> **Generated Timestamp**: 2026-10-26T10:12:25.536Z
+> **Generated Timestamp**: 2026-10-26T21:04:24.978Z
 
 ---
 
@@ -14,9 +14,9 @@
 | **Primary Source Citations** | 76 resolvable gazette URLs | 76 total citations declared | **100.0%** | VERIFIED |
 | **Temporal Validity Bounds** | 29 sections with explicit dates | 29 total bundled sections | **100.0%** | VERIFIED |
 | **Dual-Act 2025 Transition Bridges** | 9 direct tax provisions mapped | 10 direct tax provisions | **90.0%** | VERIFIED |
-| **Attached Administrative Circulars** | 30 official circulars | 6 sections across 4 domains | **100% Attached** | VERIFIED |
-| **Attached Return/Compliance Schemas** | 27 schemas/templates | 6 sections across 4 domains | **100% Attached** | VERIFIED |
-| **Cryptographic Merkle Verification** | 20 bundle files verified | SHA-256 Merkle root digest | **0 Mismatches** | VERIFIED |
+| **Attached Administrative Circulars** | 30 official circulars | 29 provisions across active domains | **100% Attached** | VERIFIED |
+| **Attached Return/Compliance Schemas** | 27 schemas/templates | 29 provisions across active domains | **100% Attached** | VERIFIED |
+| **Cryptographic Merkle Verification** | 86 bundle files verified | SHA-256 Merkle root digest | **0 Mismatches** | VERIFIED |
 
 ---
 

package/docs/DOMAIN_BREADTH_AND_DEPTH_COMPARISON.md

@@ -2,7 +2,7 @@
 ## Public Package Seed vs. Full Sovereign Operating Engine
 
 > **Document Version**: `1.0.0`  
-> **Package**: `@mudraforge/statutory` (v2.4.0)  
+> **Package**: `@mudraforge/statutory` (v2.9.0)  
 > **Enterprise Sovereign Engine**: MudraForge Adesha Sovereign Runtime  
 > **Specification**: Google Open Knowledge Format (OKF v0.2)  
 

package/docs/ENTERPRISE_GOVERNANCE.md

@@ -3,7 +3,7 @@
 
 > **Document Type**: Architecture & Enterprise Governance Specification  
 > **Target Audience**: Chief Financial Officers (CFOs), Heads of Finance, Enterprise Security & Risk Teams  
-> **Underlying Substrate**: MudraForge Statutory Knowledge Layer (OKF)  
+> **Underlying Substrate**: MudraForge Statutory Knowledge Layer (OKF) — [`@mudraforge/statutory`](../README.md)  
 
 ---
 
@@ -17,25 +17,86 @@ When modern organizations adopt AI agents for finance operations, the primary ri
 
 MudraForge Adesha was designed to establish an impenetrable **Execution Boundary** between generative AI assistance and real-world money movement.
 
+> **The Core Thesis of Autonomous Finance**:  
+> *The dangerous moment in finance AI isn't when the model is wrong. It's when its output becomes a payment instruction.*  
+> 
+> In marketing, an AI hallucination is a typo. In accounts payable, an unhandled bank timeout can trigger a retry that double-pays a vendor.  
+> 
+> Hardening the financial runtime for **Adesha, MudraForge's organizational AI**, our principle is simple:  
+> **Reasoning can be probabilistic, but financial execution needs deterministic boundaries.**
+
+---
+
+## 2. The Three-Tier Architecture & Operational Boundaries
+
+To ensure complete clarity for developers, auditors, and enterprise clients, MudraForge establishes three distinct architectural tiers with strict operational boundaries:
+
+| Tier | Component | Repository & Distribution | Pricing & License | Operational Status |
+| :--- | :--- | :--- | :--- | :--- |
+| **Tier 1** | **Open-Source Statutory Commons** (`@mudraforge/statutory`) | Public GitHub (`mondeep0123/mudraforge-statutory`) & NPM Registry | **100% Free** (MIT License / CC BY 4.0 Data) | **`CURRENT_PRODUCTION`** (Working offline software) |
+| **Tier 2** | **Hosted Statutory API & Edge Sync** | Cloudflare Global Anycast Edge (`api.mudraforge.in`) | Best-Effort Free Beta (Metered Cloud API) | **`CURRENT_BETA`** (Edge endpoints & caching) |
+| **Tier 3** | **Commercial Adesha Runtime** | Enterprise Private VPC / On-Premise Worker Deployment | Commercial Enterprise SaaS | **`PILOT_STAGE_INTERNAL`** / **`SANDBOX_VALIDATED`** |
+
+### Precise Status Classifications across Capabilities
+
+To ensure epistemic honesty and prevent conflating tested prototypes with general availability:
+
+- **`CURRENT_PRODUCTION` (Working, Publicly Inspectable Software)**:
+  - Bundled OKF statutory corpus (29 provisions across 5 legal domains).
+  - Pure deterministic calculators in `src/calculators.js` (Corporate Tax, LUT Export, TP ALP, Section 79, Ind AS 21/109).
+  - Zero-network CLI (`mudraforge-statutory` doctor, crosswalk, diff, verify, browse).
+  - Cryptographic SHA-256 Merkle root integrity verifier (`npm run manifest:check`).
+  - Native AI Agent Skill (`SKILL.md`) for offline agent runtime inspection.
+
+- **`SANDBOX_VALIDATED` (Tested Under Realistic Simulation & Integration Sandboxes)**:
+  - Live Zoho Books general ledger balanced double-entry writeback (tested against sandbox and live accounts with readback).
+  - RazorpayX corporate banking sandbox payout dispatch (`SETTLEMENT_LIVE_SANDBOX`), HMAC-SHA256 webhook ingestion, and clearinghouse reversal interception.
+  - Multi-process lock contention testing verifying single-use lease acquisition across competing OS processes.
+
+- **`PILOT_STAGE_INTERNAL` / `PLANNED` (Enterprise Engagements Requiring Partner Onboarding)**:
+  - Direct host-to-host bank rail settlement (ICICI / HDFC corporate host-to-host RTGS/NEFT).
+  - Multi-region distributed lease coordination across Cloudflare Durable Objects.
+  - Hosted Model Context Protocol (MCP) server fleets and live multi-agent tool connectivity (strictly enterprise tier).
+
+---
+
+## 3. The Four Pillars of Autonomous Finance Execution
+
+1. **Retrieval is Not Verification**: Finding a document or matching keywords is not legal verification. Real accounting requires validating evidence against connected systems of record (including live Zoho Books / SAP ERP readback) and authenticated tenant statutory vaults.
+2. **Safe Tools Do Not Guarantee Safe Workflows**: An AI agent can call individually safe API tools and still coordinate an unauthorized or illegal transaction. Generative models coordinate investigations; deterministic code calculates statutory taxes and enforces ledger invariants (*Rule 11: Agreement with the Engine ≠ Agreement with the Law*).
+3. **Preventing Silent Financial Drift**: Deterministic code computes numbers. RFC 8785 JSON Canonicalization Scheme (JCS) and SHA-256 bind calculation results to a verifiable fingerprint. The hash does not compute—it detects changes between calculation, human authorization, and execution. If the result no longer matches the fingerprint, the workflow halts.
+4. **Testing Payment Boundaries Against Failure**: Single-use CAS leases prevent duplicate payments under concurrent races. Formal TLA+ modeling with the TLC Model Checker explored all 361 reachable states in our configured distributed model with 0 invariant violations and caught 4 injected defects.
+
 ---
 
-## 2. Seven-Stage Governance Chain of Custody
+## 4. Seven-Stage End-to-End AP Governance Lifecycle
 
 Every financial transaction in MudraForge Adesha passes through seven sequential verification gates before any funds can move or any ledger can mutate:
 
 ```
-1. Input Ingestion     ──► Digitally signed IRP e-Invoice QR code & binary hash verification
-2. Statutory Substrate ──► Deterministic tax calculation under Open Knowledge Format (OKF)
-3. Canonical Result    ──► Tamper-evident RFC 8785 (JCS) normalization & SHA-256 seal
-4. Presentation Lock   ──► Automated prose auditor verifies generative text matches numbers
-5. Single-Use Lease    ──► Cryptographically bound lease issued with Maker-Checker token
-6. Zero-Trust Outflow  ──► Atomic database Compare-and-Swap (CAS) prevents duplicate execution
-7. Ledger Equilibrium ──► Source-bound lines balanced to ₹0.00 posted post-bank UTR receipt
+Stage 1: Invoice Ingestion (IRP QR Code / PDF & Vendor Validation)
+    ↓
+Stage 2: OKF Rule Resolution (Sub-1ms Local Offline Lookup)
+    ↓
+Stage 3: Deterministic Statutory Computation (Excess Math & GST Unbundling)
+    ↓
+Stage 4: Cryptographic Payment Authorization Lease (Single-Use Atomic CAS Gate)
+    ↓
+Stage 5: Human-in-the-Loop Authority Harness (CFO Biometric Passkey / Mobile)
+    ↓
+Stage 6: Bank Rail Settlement (Host-to-Host Corporate RTGS / Sandbox Rail)
+    ↓
+Stage 7: General Ledger Balanced Double-Entry Writeback (ERP Equilibrium: ₹0.00 Discrepancy)
+```
+
+Run this audited 7-stage AP simulation directly in your local terminal:
+```bash
+npm run example:trace
 ```
 
 ---
 
-## 3. Cryptographic Single-Use Payment Authorization Leases
+## 5. Cryptographic Single-Use Payment Authorization Leases
 
 In Adesha, banking adapters (such as RazorpayX, Mercury, or host-to-host SFTP connections) operate within a **Zero-Trust Execution Boundary**.
 
@@ -64,7 +125,7 @@ A payment lease is cryptographically bound to seven immutable parameters:
 
 ---
 
-## 4. Presentation Consistency Lock & Automated Prose Auditor
+## 6. Presentation Consistency Lock & Automated Prose Auditor
 
 Generative language models regularly drop trailing zeros or swap figures when drafting summaries for human reviewers. 
 
@@ -77,22 +138,20 @@ Adesha enforces a **Presentation Consistency Lock**:
 
 ---
 
-## 5. Enterprise Risk & Operational Controls
-
-### 1. Penny-Drop Verification
-Before any vendor account can be bound to a payment lease, it must complete an automated automated penny-drop verification via NPCI/IMPS with a verified name-match score $\ge 95\%$.
+## 7. OpenSSF Packaging vs. Full Security Assurance
 
-### 2. 48-Hour Change-Control Cooling Lock
-Any alteration to vendor bank details in the enterprise master triggers an immediate **48-hour cooling-off lock**, requiring dual CFO re-authorization before leases can bind to the updated account.
-
-### 3. Structural Secret Isolation
-Banking API credentials (API keys, OAuth client secrets, mTLS certificates) reside inside an isolated secret boundary accessible exclusively through a cryptographic signing module that demands an active, unconsumed `PaymentAuthorizationLease`.
+In accordance with OpenSSF (Open Source Security Foundation) npm best practices:
+- **Packaging Hygiene**: Zero runtime dependencies, offline-first execution, and `.npmrc` with `ignore-scripts=true` neutralize install-time supply chain attacks.
+- **Cryptographic Non-Tampering**: SHA-256 Merkle root manifests certify byte-level distribution fidelity.
+- **Epistemic Honesty**: These packaging strengths do not replace independent legal counsel, statutory audit certification, or runtime multi-region crash testing. Organizations must evaluate autonomous finance systems against end-to-end integration boundaries.
 
 ---
 
-## 6. Commercial Engagement & Enterprise Pilots
+## 8. Commercial Engagement & Enterprise Pilots
+
+The full Adesha Autonomous Governance Runtime is delivered as a managed enterprise deployment integrated with your corporate ERP (Zoho Books, SAP S/4HANA, NetSuite) and banking partners.
 
-The full Adesha Autonomous Governance Runtime is delivered as a managed enterprise deployment integrated with your corporate ERP (Zoho Books, SAP, NetSuite) and banking partners.
+To evaluate Adesha in read-only shadow mode against historical accounts payable records, review the [Supervised Shadow Pilot Evaluation Guide](./PILOT_EVALUATION_GUIDE.md).
 
 For enterprise architecture discussions, pilot deployments, or API keys:
 - **Email**: [hello@mudraforge.in](mailto:hello@mudraforge.in) or [support@mudraforge.in](mailto:support@mudraforge.in)