@mudraforge/statutory 2.9.0 → 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/README.md +105 -124
- package/SKILL.md +7 -2
- package/bin/cli.js +215 -8
- package/docs/ARCHITECTURE.md +8 -8
- package/docs/ARCHITECTURE_DECISIONS.md +4 -3
- package/docs/CATALOG.md +1 -1
- package/docs/CORPUS_QUALITY.md +5 -5
- package/docs/DOMAIN_BREADTH_AND_DEPTH_COMPARISON.md +1 -1
- package/docs/ENTERPRISE_GOVERNANCE.md +81 -22
- package/docs/PILOT_EVALUATION_GUIDE.md +155 -90
- package/docs/PROVENANCE.md +4 -4
- package/docs/VERIFICATION.md +7 -7
- package/okf/manifest.json +1 -1
- package/package.json +18 -1
- package/src/constants.js +10 -0
- package/src/index.js +92 -13
- package/src/outcomes.js +483 -0
- package/types/index.d.ts +55 -0
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
---
|
|
9
9
|
|
|
10
|
+
## [2.10.0] - 2026-10-27
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- **Canonical Statutory Outcomes & Semantic Disposition Dictionary (`src/outcomes.js`)**:
|
|
14
|
+
- Cataloged 12 canonical statutory outcomes and non-numerical dispositions (`DETERMINED_APPLICABLE`, `DETERMINED_THRESHOLD_NOT_MET`, `INDETERMINATE_BUYER_TURNOVER_UNVERIFIED`, `INDETERMINATE_PENDING_TRANSACTION_DATE`, `SUNSET_OMITTED`, `PENALTY_RATE_MANDATED`, `DISQUALIFIED_FROM_ZERO_RATING`, `REQUIRES_HUMAN_REVIEW`, `MISSING_EVIDENCE_HOLD`, `INDETERMINATE_DISPUTE_UNRESOLVED`, `INDETERMINATE_RECIPIENT_COUNTRY_REQUIRED`, `MSME_DELAYED_PAYMENT_INTEREST_DUE`).
|
|
15
|
+
- Added programmatic functions `getStatutoryOutcomes(provision, options)` with offline-first resolution and edge synchronization.
|
|
16
|
+
- Added programmatic explanation function `explainStatutoryDisposition(codeOrQuery, options)` supporting exact matches, registered aliases, broad category groups (`INDETERMINATE`), and fuzzy keyword search.
|
|
17
|
+
- Added automatic outcome explanation enrichment helper `enrichWithOutcomeExplanation(result, options)` injecting plain-English descriptions, actionable remedies, statutory consequences, and structured missing-fact schemas.
|
|
18
|
+
- **Interactive CLI Explain & Outcomes Engine (`bin/cli.js`)**:
|
|
19
|
+
- `mudra-statutory outcomes [provision]`: Lists available dispositions, trigger preconditions, and recommended actions, with `--verbose` (`-v`) for deep remediation guidance and `--json` for automation.
|
|
20
|
+
- `mudra-statutory explain <code_or_status>`: Explains any disposition or indeterminacy reason (aliases: `explain`, `why`, `remedy`).
|
|
21
|
+
- **CLI Update Snoozing & Notification Governance**:
|
|
22
|
+
- Automated non-intrusive update check banner on human interactive CLI execution.
|
|
23
|
+
- Added `mudra-statutory check-update --ignore` to persistently snooze notices for the current release.
|
|
24
|
+
- Added `--no-update-check` global flag and `MUDRA_NO_UPDATE_NOTIFIER=1` environment variable.
|
|
25
|
+
- **Extended Test Suite (88/88 Test Suites Passing)**:
|
|
26
|
+
- Added Tests 81–88 verifying outcomes retrieval, explanation lookup, CLI integration, update snoozing, and automatic explanation enrichment.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
10
30
|
## [2.9.0] - 2026-10-26
|
|
11
31
|
|
|
12
32
|
### Added
|
package/README.md
CHANGED
|
@@ -1,50 +1,81 @@
|
|
|
1
|
-
#
|
|
1
|
+
# MudraForge Adesha — Statutory Knowledge & Governance Substrate (`@mudraforge/statutory`)
|
|
2
2
|
|
|
3
|
-
> **Open
|
|
4
|
-
> *
|
|
3
|
+
> **The Open Trust Anchor for Autonomous Finance AI**
|
|
4
|
+
> *MudraForge Adesha is an autonomous organizational AI for commercial finance and accounts payable. Its statutory knowledge and deterministic calculation layer is open-sourced here as `@mudraforge/statutory` so engineering teams, Chief Financial Officers, and tax practitioners can independently inspect, verify, and trust the legal and computational foundation it runs on.*
|
|
5
5
|
|
|
6
6
|
[](https://www.npmjs.com/package/@mudraforge/statutory)
|
|
7
7
|
[](https://github.com/mondeep0123/mudraforge-statutory/actions/workflows/ci.yml)
|
|
8
8
|
[](https://opensource.org/licenses/MIT)
|
|
9
|
-
[-success.svg)](https://nodejs.org)
|
|
10
10
|
[](https://cloud.google.com/blog)
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
|
-
## 30-Second Quick Start
|
|
14
|
+
## 30-Second Quick Start (100% Offline, Zero Dependencies)
|
|
15
|
+
|
|
16
|
+
Install and run locally in any Node.js 18+, Bun, or Deno environment with **zero network requests and zero API keys required**:
|
|
15
17
|
|
|
16
18
|
```bash
|
|
17
19
|
npm install @mudraforge/statutory
|
|
18
20
|
```
|
|
19
21
|
|
|
20
22
|
```javascript
|
|
21
|
-
import {
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
//
|
|
29
|
-
const
|
|
30
|
-
console.log(
|
|
23
|
+
import {
|
|
24
|
+
lookupStatute,
|
|
25
|
+
calculateCorporateTaxMatVsConcessional,
|
|
26
|
+
evaluatePlaceOfSupplyAndLut,
|
|
27
|
+
isStatuteActive
|
|
28
|
+
} from '@mudraforge/statutory';
|
|
29
|
+
|
|
30
|
+
// 1. Instant offline statutory lookup (sub-1ms, zero network calls, zero API keys)
|
|
31
|
+
const section = await lookupStatute('194Q');
|
|
32
|
+
console.log(section.statute.title);
|
|
33
|
+
// => "Deduction of tax at source on payment of a certain sum for purchase of goods"
|
|
34
|
+
|
|
35
|
+
// 2. Deterministic Corporate Tax: MAT (Sec 115JB) vs Concessional (Sec 115BAA)
|
|
36
|
+
const tax = calculateCorporateTaxMatVsConcessional({
|
|
37
|
+
turnoverPrecedingFyInr: 300000000, // ₹30 Cr turnover
|
|
38
|
+
netProfitBeforeTaxInr: 100000000, // ₹10 Cr NPBT
|
|
39
|
+
normalTaxAdditionsInr: 10000000, // ₹1 Cr additions
|
|
40
|
+
normalTaxDeductionsInr: 2000000 // ₹20 Lakhs deductions
|
|
41
|
+
});
|
|
42
|
+
console.log(tax.comparisonSummary.recommendedRegime); // "SECTION_115BAA"
|
|
43
|
+
console.log(tax.comparisonSummary.netCashSavingsInr); // 3764800 (Net savings ₹37.64L)
|
|
44
|
+
|
|
45
|
+
// 3. Place of Supply & Zero-Rated Export of Services under LUT (IGST Sec 16)
|
|
46
|
+
const exportEvaluation = evaluatePlaceOfSupplyAndLut({
|
|
47
|
+
supplierStateCode: '27', // Maharashtra
|
|
48
|
+
recipientCountryCode: 'US', // United States
|
|
49
|
+
hasValidLut: true, // Letter of Undertaking in Form GST RFD-11
|
|
50
|
+
isConvertibleForexReceivedOrRbiInr: true, // Sec 2(6)(iv) FIRC/e-BRC
|
|
51
|
+
invoiceAmountInr: 500000 // ₹5,00,000 export invoice
|
|
52
|
+
});
|
|
53
|
+
console.log(exportEvaluation.statutoryDetermination); // "ZERO_RATED_EXPORT_UNDER_LUT"
|
|
54
|
+
console.log(exportEvaluation.igstPayableInr); // 0 (0% IGST)
|
|
31
55
|
|
|
32
|
-
//
|
|
33
|
-
const
|
|
34
|
-
console.log(
|
|
56
|
+
// 4. Temporal Legislative Sunset Check
|
|
57
|
+
const isActive = await isStatuteActive('206C(1H)', '2025-06-01');
|
|
58
|
+
console.log(isActive); // false (Omitted w.e.f. 1 April 2025 by Finance Act, 2025)
|
|
35
59
|
```
|
|
36
60
|
|
|
37
61
|
---
|
|
38
62
|
|
|
39
|
-
## Overview
|
|
63
|
+
## Overview: Why We Open-Source Adesha's Statutory Substrate
|
|
64
|
+
|
|
65
|
+
In enterprise finance, no CFO, audit committee, or enterprise risk officer will permit an autonomous AI agent to propose payment instructions or touch the corporate general ledger if its tax withholding and regulatory logic is an opaque, black-box prompt. Large language models hallucinate tax rates, invert statutory obligations, and defend computational errors (*Rule 11: Agreement with the Engine ≠ Agreement with the Law*).
|
|
40
66
|
|
|
41
|
-
|
|
67
|
+
**MudraForge Adesha** resolves this through deliberate architectural separation:
|
|
42
68
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
* **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).
|
|
69
|
+
1. **The Open Trust Anchor (This Package — `@mudraforge/statutory`)**: The deterministic statutory substrate. It structures 29 primary laws across 5 regulatory domains under Google's Open Knowledge Format (OKF v0.2), provides 7 pure mathematical calculators, and verifies legal ground truth with cryptographic Merkle integrity—100% offline with zero dependencies. Anyone can inspect, test, fork, or embed this layer freely in their own financial applications.
|
|
70
|
+
2. **The Governed Execution Platform (Adesha Enterprise Runtime)**: When an organization deploys Adesha, it receives the complete autonomous finance AI system: multimodal invoice interpretation, 3-way PO matching, deterministic statutory validation, single-use cryptographic payment leases, CFO biometric approval, host-to-host bank rail settlement, and balanced double-entry ERP general ledger writebacks (Zoho Books, SAP S/4HANA, NetSuite).
|
|
46
71
|
|
|
47
|
-
>
|
|
72
|
+
> **The Core Thesis of Autonomous Finance**:
|
|
73
|
+
> *Reasoning can be probabilistic, but financial execution needs deterministic boundaries.*
|
|
74
|
+
> Knowing what the law says is not the same as having authority to disburse funds. This package guarantees statutory truth; Adesha governs consequential execution.
|
|
75
|
+
|
|
76
|
+
> For cryptographic root digests, normative specifications, and formal assurance artifacts, see [docs/PROVENANCE.md](./docs/PROVENANCE.md).
|
|
77
|
+
> For the enterprise execution platform architecture, see [docs/ENTERPRISE_GOVERNANCE.md](./docs/ENTERPRISE_GOVERNANCE.md).
|
|
78
|
+
> To test Adesha against your historical accounting records in read-only shadow mode, see [docs/PILOT_EVALUATION_GUIDE.md](./docs/PILOT_EVALUATION_GUIDE.md).
|
|
48
79
|
|
|
49
80
|
---
|
|
50
81
|
|
|
@@ -60,7 +91,7 @@ console.log(statute.statute.title); // MSMED statutory payment timelines & compo
|
|
|
60
91
|
- [2. Finance Software & Accounts-Payable Workflows](#2-finance-software--accounts-payable-workflows)
|
|
61
92
|
- [3. Developer Tooling & Audit Verification](#3-developer-tooling--audit-verification)
|
|
62
93
|
- [Product Capability Status & Operational Boundaries](#product-capability-status--operational-boundaries)
|
|
63
|
-
- [
|
|
94
|
+
- [Supervised Shadow Pilot Evaluation Guide (docs/PILOT_EVALUATION_GUIDE.md)](./docs/PILOT_EVALUATION_GUIDE.md)
|
|
64
95
|
- [Legal Domains Currently Covered](#legal-domains-currently-covered)
|
|
65
96
|
- [Structured OKF Directory Hierarchy](#structured-okf-domain-hierarchy-zero-token-discovery)
|
|
66
97
|
- [Canonical Edge Synchronization](#canonical-edge-synchronization-full-statutory-universe)
|
|
@@ -90,45 +121,15 @@ console.log(statute.statute.title); // MSMED statutory payment timelines & compo
|
|
|
90
121
|
|
|
91
122
|
---
|
|
92
123
|
|
|
93
|
-
##
|
|
94
|
-
|
|
95
|
-
> **The Dangerous Moment in Finance AI**:
|
|
96
|
-
> *The dangerous moment in finance AI isn't when the model is wrong. It's when its output becomes a payment instruction.*
|
|
97
|
-
>
|
|
98
|
-
> In marketing, an AI hallucination is a typo. In accounts payable, an unhandled bank timeout can trigger a retry that double-pays a vendor.
|
|
99
|
-
>
|
|
100
|
-
> Hardening the financial runtime for **Adesha, MudraForge's organizational AI**, our principle is simple:
|
|
101
|
-
> **Reasoning can be probabilistic, but financial execution needs deterministic boundaries.**
|
|
124
|
+
## Separation of Statutory Knowledge from Autonomous Execution
|
|
102
125
|
|
|
103
|
-
|
|
126
|
+
A fundamental design invariant of MudraForge is: **Knowing what the law says is not the same as having authority to disburse corporate funds.**
|
|
104
127
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
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.
|
|
108
|
-
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. Edge execution runs on Cloudflare Workers V8 isolates with zero-discrepancy double-entry ledger writebacks.
|
|
128
|
+
- **The Open-Source Commons (`@mudraforge/statutory`)**: Provides declarative statutory truth, temporal boundaries, and pure deterministic calculators. All functions enforce `isAuthorizedToDisburse: false`. Calculation never authorizes autonomous money movement.
|
|
129
|
+
- **The Governed Execution Platform (Adesha)**: Manages consequential real-world operations—single-use payment authorization leases, dual-custody mobile authorization, banking rail integration, and balanced ERP general ledger writebacks.
|
|
109
130
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
```
|
|
113
|
-
Stage 1: Invoice Ingestion (IRP QR / PDF)
|
|
114
|
-
↓
|
|
115
|
-
Stage 2: OKF Rule Resolution (Sub-1ms Local Offline Lookup)
|
|
116
|
-
↓
|
|
117
|
-
Stage 3: Deterministic Statutory Computation (Excess Math & GST Unbundling)
|
|
118
|
-
↓
|
|
119
|
-
Stage 4: Cryptographic Payment Authorization Lease (Single-Use Atomic CAS Gate)
|
|
120
|
-
↓
|
|
121
|
-
Stage 5: Human-in-the-Loop Authority Harness (CFO Biometric Passkey / Mobile)
|
|
122
|
-
↓
|
|
123
|
-
Stage 6: Bank Rail Settlement (Host-to-Host Corporate RTGS)
|
|
124
|
-
↓
|
|
125
|
-
Stage 7: General Ledger Balanced Double-Entry Writeback (ERP Equilibrium: ₹0.00 Discrepancy)
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
Run this audited 7-stage AP simulation directly in your local terminal:
|
|
129
|
-
```bash
|
|
130
|
-
npm run example:trace
|
|
131
|
-
```
|
|
131
|
+
> For complete enterprise architecture specifications, TLC model checking proofs, and the 7-stage AP governance lifecycle, see [docs/ENTERPRISE_GOVERNANCE.md](./docs/ENTERPRISE_GOVERNANCE.md).
|
|
132
|
+
> To run a local simulation of the modeled 7-stage AP trace: `npm run example:trace`.
|
|
132
133
|
|
|
133
134
|
---
|
|
134
135
|
|
|
@@ -252,19 +253,20 @@ To ensure absolute clarity for developers, finance leaders, prospective pilot cu
|
|
|
252
253
|
|
|
253
254
|
| Subsystem / Capability | Operational Classification | Availability / Access | Current Verification Evidence |
|
|
254
255
|
| :--- | :--- | :--- | :--- |
|
|
255
|
-
| **Bundled OKF Statutory Corpus (
|
|
256
|
+
| **Bundled OKF Statutory Corpus (29 Provisions across 5 Domains)** | **Public Package** | Shipped in repository & release candidates (`okf/`) | 80/80 test suites passing; deterministic SHA-256 Merkle root |
|
|
256
257
|
| **Zero-Network CLI (`mudraforge-statutory`)** | **Public Package** | Immediate via `npx @mudraforge/statutory` | `bin/cli.js` verified across Windows and Linux |
|
|
257
258
|
| **Vendor-Neutral Conformance Suite** | **Public Package** | Immediate via `conformance/` (`npm run conformance`) | 12/12 fixture tests passing |
|
|
258
259
|
| **Local Query SDK (`src/index.js`)** | **Public Package** | Immediate via `import { lookupStatute }` | Zero runtime dependencies; offline temporal state evaluation |
|
|
259
260
|
| **Synthetic AP Execution Trace (`examples/`)** | **Public Package (Modeled Demo)** | Immediate via `npm run example:trace` | Synthetic invoice trace demonstrating 7-stage lifecycle with modeled fixtures |
|
|
260
261
|
| **Cloudflare Anycast Edge Sync** | **Public Edge Service** | Free Beta via `api.mudraforge.in` | Global edge sync (`npx @mudraforge/statutory sync`) with ETag 304 caching |
|
|
261
262
|
| **Interactive API Documentation** | **Public Edge Service** | Free Beta via `/api/v1/statutory/docs` | OpenAPI 3.1 schema and interactive documentation rendered on Anycast edge |
|
|
262
|
-
| **Deterministic
|
|
263
|
+
| **Deterministic Calculators (7 Pure Functions)** | **Public Package** | Immediate via `@mudraforge/statutory/calculators` | Corporate tax MAT vs concessional, GST POS/LUT, TP ALP, Section 79, Ind AS 109, Section 288B |
|
|
264
|
+
| **Hosted AP Engine & Cumulative Spend Tracking** | **Enterprise Edge / Internal** | Metered Enterprise API (Selective) | Hosted Section 194Q cumulative spend & Section 16 MSMED interest engine |
|
|
263
265
|
| **Dual-Custody Mobile Approval Harness** | **Enterprise Internal / Pilot** | Enterprise Pilot Proposal | Mobile passkey approval prototype & TLA+ state machine (`specs/`) |
|
|
264
266
|
| **ERP Two-Way Connectors (SAP/Tally/Zoho)** | **Enterprise Internal / Pilot** | Custom Enterprise Pilot Integration | Shadow-mode test connectors; no turnkey plug-ins shipped |
|
|
265
267
|
| **Bank Rail API Adapters (ICICI/HDFC/RazorpayX)** | **Enterprise Internal / Pilot** | Custom Enterprise Pilot Integration | Modeled sandbox adapters requiring corporate bank partner onboarding |
|
|
266
268
|
|
|
267
|
-
> **Operational Distinction**: Items classified as **Public Package** and **Public Edge Service** represent working, independently inspectable software. Items classified as **Enterprise Internal / Pilot** represent developing or internal capabilities of the commercial Adesha runtime. Execution traces in `examples/` use synthetic test data; they do not represent active commercial bank or live customer ERP deployments. Organizations interested in testing MudraForge against real accounting data should review the [
|
|
269
|
+
> **Operational Distinction**: Items classified as **Public Package** and **Public Edge Service** represent working, independently inspectable software. Items classified as **Enterprise Internal / Pilot** represent developing or internal capabilities of the commercial Adesha runtime. Execution traces in `examples/` use synthetic test data; they do not represent active commercial bank or live customer ERP deployments. Organizations interested in testing MudraForge against real accounting data should review the [Supervised Shadow Pilot Evaluation Guide](./docs/PILOT_EVALUATION_GUIDE.md).
|
|
268
270
|
|
|
269
271
|
---
|
|
270
272
|
|
|
@@ -276,14 +278,14 @@ To ensure clarity for developers, CAs, and prospective enterprise clients, the o
|
|
|
276
278
|
| :--- | :--- | :--- | :--- |
|
|
277
279
|
| **Pricing & License** | **100% Free** (MIT Code / CC BY 4.0 Data) | **Best-Effort Free Beta** (Transitions to Metered) | **Commercial Enterprise SaaS** |
|
|
278
280
|
| **Execution Location** | 100% Local Filesystem (0 Network Calls) | Cloudflare Edge (Global 300+ PoPs, typical 20–80ms Anycast latency) | Private Enterprise VPC / On-Premise Worker |
|
|
279
|
-
| **Statutory Knowledge** | Bundled Starter Seed (
|
|
281
|
+
| **Statutory Knowledge** | Bundled Starter Seed (29 Verified Sections across 5 Domains) | 29 Active Provisions (Roadmap Catalog in expansion) | Full Sovereign Catalog + Custom Private Enterprise Contracts |
|
|
280
282
|
| **Lookup Engine** | Exact code, alias & folder path resolution | System-1 Semantic Intent & Rule Discovery | Multi-tenant RAG & Context Assembler |
|
|
281
283
|
| **Temporal Status** | Offline deterministic evaluation (`computeTemporalStatus`) | Live temporal state machine resolution | In-flight temporal locks across transaction lifecycle |
|
|
282
|
-
| **Deterministic Calculators**|
|
|
284
|
+
| **Deterministic Calculators**| **Included** (7 Zero-dependency pure mathematical calculators exported in `src/calculators.js`) | Hosted calculation endpoint (`POST /calculate`) | Full arithmetic engine with ₹50L excess & 3x RBI interest |
|
|
283
285
|
| **Payment Authorization** | *Not included* | *Not included* | **Single-Use Cryptographic Payment Leases (TLA+ verified)** |
|
|
284
286
|
| **Banking Execution** | *Not included* | *Not included* | **Host-to-Host Bank Rails (RazorpayX / ICICI / HDFC)** |
|
|
285
287
|
| **ERP Writebacks** | *Not included* | *Not included* | **Balanced double-entry journal writebacks (SAP / Zoho)** |
|
|
286
|
-
| **How to Access** | `npm install @mudraforge/statutory` | `npx @mudraforge/statutory sync` | Review [Pilot Guide](./docs/PILOT_EVALUATION_GUIDE.md) / Contact `hello@mudraforge.in` |
|
|
288
|
+
| **How to Access** | `npm install @mudraforge/statutory` | `npx @mudraforge/statutory sync` | Review [Supervised Shadow Pilot Guide](./docs/PILOT_EVALUATION_GUIDE.md) / Contact `hello@mudraforge.in` |
|
|
287
289
|
|
|
288
290
|
> **Operational Distinction**: This open-source repository provides the **declarative knowledge foundation**. It does not perform live banking transfers, hold funds, or mutate corporate ERP databases. Those consequential actions are strictly isolated within the **MudraForge Adesha Enterprise Governance Engine** (see [`docs/ENTERPRISE_GOVERNANCE.md`](./docs/ENTERPRISE_GOVERNANCE.md)).
|
|
289
291
|
|
|
@@ -302,7 +304,7 @@ The MudraForge Statutory project publishes an open, locally usable statutory kno
|
|
|
302
304
|
|
|
303
305
|
## Structured OKF Domain Hierarchy (Zero-Token Discovery)
|
|
304
306
|
|
|
305
|
-
Rules are organized into **
|
|
307
|
+
Rules are organized into **five foundational regulatory domains**, complete with official circulars, statutory notifications, and compliance form schemas:
|
|
306
308
|
|
|
307
309
|
```
|
|
308
310
|
okf/
|
|
@@ -437,9 +439,26 @@ npx @mudraforge/statutory diff --section 194H
|
|
|
437
439
|
npx @mudraforge/statutory diff --since 2025-01-01
|
|
438
440
|
npx @mudraforge/statutory diff --domain indirect_tax_gst
|
|
439
441
|
|
|
442
|
+
# Inspect statutory outcomes, semantic disposition codes, and missing facts
|
|
443
|
+
npx @mudraforge/statutory outcomes
|
|
444
|
+
npx @mudraforge/statutory outcomes 194Q
|
|
445
|
+
npx @mudraforge/statutory outcomes 194Q --verbose
|
|
446
|
+
npx @mudraforge/statutory outcomes MSMED-15-16
|
|
447
|
+
|
|
448
|
+
# In-depth explanation of indeterminate states, missing facts & remediation steps
|
|
449
|
+
npx @mudraforge/statutory explain INDETERMINATE
|
|
450
|
+
npx @mudraforge/statutory explain BUYER_TURNOVER_UNVERIFIED
|
|
451
|
+
npx @mudraforge/statutory explain MISSING_EVIDENCE_HOLD
|
|
452
|
+
|
|
453
|
+
# Check package updates or snooze notifications for current version
|
|
454
|
+
npx @mudraforge/statutory check-update
|
|
455
|
+
npx @mudraforge/statutory check-update --ignore
|
|
456
|
+
|
|
440
457
|
# Output machine-parseable JSON for CI/CD or jq integration
|
|
441
458
|
npx @mudraforge/statutory crosswalk 194Q --credit 2026-03-25 --payment 2026-04-10 --json
|
|
442
459
|
npx @mudraforge/statutory diff --section 194H --json
|
|
460
|
+
npx @mudraforge/statutory outcomes 194Q --json
|
|
461
|
+
npx @mudraforge/statutory explain BUYER_TURNOVER_UNVERIFIED --json
|
|
443
462
|
npx @mudraforge/statutory verify --json
|
|
444
463
|
npx @mudraforge/statutory doctor --json --offline
|
|
445
464
|
|
|
@@ -463,65 +482,27 @@ Calling pipelines and CI/CD audit steps can inspect `$?` directly:
|
|
|
463
482
|
|
|
464
483
|
---
|
|
465
484
|
|
|
466
|
-
##
|
|
467
|
-
|
|
468
|
-
To access the **System-1 semantic discovery search**, **Analysis Mode output**, and **Deterministic Calculation Engines**, initialize `StatutoryClient` with an Enterprise API key:
|
|
469
|
-
|
|
470
|
-
```javascript
|
|
471
|
-
import { StatutoryClient } from '@mudraforge/statutory';
|
|
485
|
+
## Commercial & Enterprise Platform Ecosystem
|
|
472
486
|
|
|
473
|
-
|
|
474
|
-
tier: 'ENTERPRISE_PAID',
|
|
475
|
-
apiKey: process.env.MUDRA_STATUTORY_API_KEY // Available via hello@mudraforge.in
|
|
476
|
-
});
|
|
487
|
+
`@mudraforge/statutory` is the open-source, zero-dependency statutory ground-truth substrate of the MudraForge ecosystem. For organizations requiring consequential financial execution, hosted agent tools, or managed infrastructure:
|
|
477
488
|
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
489
|
+
### 1. Governed Execution Platform (MudraForge Adesha)
|
|
490
|
+
While `@mudraforge/statutory` calculates what the law requires, **Adesha** governs real-world financial execution:
|
|
491
|
+
- **Single-Use Payment Authorization Leases**: Atomic Compare-and-Swap (CAS) leases cryptographically bound to invoice hash, vendor legal entity, and authorized net wire amount.
|
|
492
|
+
- **Human-in-the-Loop Authority Harness**: Maker-checker workflows requiring CFO biometric passkey approval.
|
|
493
|
+
- **Host-to-Host Banking Rail Integration**: Dispatches payouts via corporate banking gateways with signed webhook verification and clearinghouse reversal interception.
|
|
494
|
+
- **ERP General Ledger Writebacks**: Automatically posts balanced double-entry vouchers to Zoho Books, SAP S/4HANA, or NetSuite upon settlement confirmation.
|
|
495
|
+
- *Detailed Architecture*: See [docs/ENTERPRISE_GOVERNANCE.md](./docs/ENTERPRISE_GOVERNANCE.md).
|
|
485
496
|
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
497
|
+
### 2. Hosted Model Context Protocol (MCP) Infrastructure
|
|
498
|
+
In accordance with our commercial boundary protocol:
|
|
499
|
+
- **Enterprise-Tier Tooling**: Hosted Model Context Protocol (MCP) server endpoints and live multi-agent tool connectivity are strictly commercial/enterprise features.
|
|
500
|
+
- **Enterprise Setup**: Connecting MCP clients (Claude Desktop, Cursor, Windsurf, or Antigravity) connects to enterprise-licensed infrastructure and requires an Enterprise API Key.
|
|
501
|
+
- Contact: `hello@mudraforge.in` / `support@mudraforge.in`.
|
|
489
502
|
|
|
490
|
-
###
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|---|---|---|---|---|
|
|
494
|
-
| `/api/v1/statutory/sections` | `GET` | No | 180 req/min | JSON array of indexed OKF sections |
|
|
495
|
-
| `/api/v1/statutory/lookup` | `GET` | No | 180 req/min | Parametric section details & temporal validity |
|
|
496
|
-
| `/api/v1/statutory/laws/:code` | `GET` | No | 180 req/min | Direct path statutory section lookup |
|
|
497
|
-
| `/api/v1/statutory/manifest.json` | `GET` | No | 180 req/min | Latest OKF release manifest & rootHash |
|
|
498
|
-
| `/api/v1/statutory/bundle.json` | `GET` | No | 180 req/min | Full versioned statutory bundle (ETag 304 supported) |
|
|
499
|
-
| `/api/v1/statutory/calculate` | `POST` | **Yes** (Bearer) | 45 req/min | Deterministic statutory deduction result |
|
|
500
|
-
|
|
501
|
-
### Error Semantics & Response Codes
|
|
502
|
-
|
|
503
|
-
All error responses from `@mudraforge/statutory` and the hosted edge API return structured JSON:
|
|
504
|
-
|
|
505
|
-
```json
|
|
506
|
-
{
|
|
507
|
-
"status": "ERROR",
|
|
508
|
-
"error": "API_KEY_REQUIRED",
|
|
509
|
-
"message": "Deterministic calculation engines require an Enterprise API key.",
|
|
510
|
-
"contact": "hello@mudraforge.in"
|
|
511
|
-
}
|
|
512
|
-
```
|
|
513
|
-
|
|
514
|
-
| HTTP Status | Error Code | Description / Remedy |
|
|
515
|
-
|---|---|---|
|
|
516
|
-
| `400 Bad Request` | `INVALID_AMOUNT` | Numerical value is negative, NaN, or exceeds `Number.MAX_SAFE_INTEGER`. |
|
|
517
|
-
| `400 Bad Request` | `INVALID_DATE_FORMAT` | Date string does not match ISO 8601 `YYYY-MM-DD` format. |
|
|
518
|
-
| `400 Bad Request` | `QUERY_TOO_LONG` | Section search query exceeds 64-character security ceiling. |
|
|
519
|
-
| `401 / 403 Forbidden` | `API_KEY_REQUIRED` / `INVALID_API_KEY` | Missing or invalid Enterprise API key. Contact `hello@mudraforge.in`. |
|
|
520
|
-
| `404 Not Found` | `SECTION_NOT_FOUND` | Queried section does not exist in the indexed statutory corpus. |
|
|
521
|
-
| `405 Method Not Allowed` | `METHOD_NOT_ALLOWED` | Non-GET request sent to read-only commons endpoints. |
|
|
522
|
-
| `413 Payload Too Large` | `PAYLOAD_TOO_LARGE` | JSON request body on `/calculate` exceeds 64KB security threshold. |
|
|
523
|
-
| `415 Unsupported Media` | `UNSUPPORTED_MEDIA_TYPE` | Non-JSON payload sent to calculation engine. Set `Content-Type: application/json`. |
|
|
524
|
-
| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Rate limit threshold breached. Check `Retry-After` header before retrying. |
|
|
503
|
+
### 3. Hosted Edge API & Continuous Synchronization
|
|
504
|
+
- **Hosted Edge Calculation (`/api/v1/statutory/calculate`)**: Optional cloud-hosted calculation service on Cloudflare Anycast edge for organizations integrating via REST rather than the Node.js package.
|
|
505
|
+
- **Continuous Regulatory Sync**: SLA-backed automated updates tracking Gazette of India notifications, CBDT circulars, and Finance Act amendments.
|
|
525
506
|
|
|
526
507
|
---
|
|
527
508
|
|
|
@@ -530,7 +511,7 @@ All error responses from `@mudraforge/statutory` and the hosted edge API return
|
|
|
530
511
|
The repository enforces fail-closed automated verification for schemas, temporal rules, and cryptographic digests:
|
|
531
512
|
|
|
532
513
|
```bash
|
|
533
|
-
# 1. Run full
|
|
514
|
+
# 1. Run full 88-suite multi-domain regression test
|
|
534
515
|
npm test
|
|
535
516
|
|
|
536
517
|
# 2. Validate all OKF schemas, circular YAML frontmatter, and return forms
|
package/SKILL.md
CHANGED
|
@@ -14,7 +14,7 @@ AI agents can operate in two modes:
|
|
|
14
14
|
### Mode 1: Local Filesystem Navigation (Default / Free / Offline)
|
|
15
15
|
The skill maintains a local versioned directory of statutory rules in `./okf/`:
|
|
16
16
|
- `okf/manifest.json`: Local release version & root integrity hash.
|
|
17
|
-
- `okf/<domain>/<provision>/section.json`: Individual statutory provisions organized by regulatory domain (`direct_tax`, `indirect_tax_gst`, `msme_commercial`, `international_tax`), accompanied by official executive circulars (`circulars/*.md`) and compliance forms (`forms/*.json`).
|
|
17
|
+
- `okf/<domain>/<provision>/section.json`: Individual statutory provisions organized by regulatory domain (`direct_tax`, `indirect_tax_gst`, `msme_commercial`, `international_tax`, `corporate_ma_restructuring`), accompanied by official executive circulars (`circulars/*.md`) and compliance forms (`forms/*.json`).
|
|
18
18
|
|
|
19
19
|
Agents should traverse and read these local files directly to avoid external network calls.
|
|
20
20
|
|
|
@@ -48,7 +48,12 @@ Before conducting high-stakes tax compliance analysis or audit verification:
|
|
|
48
48
|
|
|
49
49
|
---
|
|
50
50
|
|
|
51
|
-
##
|
|
51
|
+
## Model Context Protocol (MCP) & Enterprise Agent Tooling
|
|
52
|
+
|
|
53
|
+
In accordance with our commercial boundary protocol (Rule 17):
|
|
54
|
+
1. **Commercial Boundary**: Model Context Protocol (MCP) server connectivity, hosted MCP server endpoints, and live multi-agent tool execution are strictly commercial/enterprise features. The free public commons is the zero-dependency `@mudraforge/statutory` npm package and local OKF corpus.
|
|
55
|
+
2. **Enterprise Setup Protocol**: When providing setup guidance for MCP clients (e.g., Claude Desktop, Cursor, Windsurf, or Antigravity), access connects to enterprise-licensed infrastructure and requires an Enterprise API Key (`hello@mudraforge.in` / `support@mudraforge.in`).
|
|
56
|
+
3. **Local Workflows**: For free, air-gapped, and local agent workflows, agents traverse and inspect `./okf/` directories directly using standard filesystem tools with zero network reliance.
|
|
52
57
|
|
|
53
58
|
1. **Never Hallucinate Rates or Thresholds**:
|
|
54
59
|
Statutory rates and thresholds are enacted law, not language model predictions. Always verify rates and cumulative thresholds against the live substrate.
|