@mudraforge/statutory 2.9.0 → 2.10.0

package/docs/PILOT_EVALUATION_GUIDE.md

@@ -1,149 +1,214 @@
-# MudraForge Adesha — Proposed Accounts Payable Pilot Evaluation Guide
-## Protocol for Bounded Historical Shadow Audits
+# MudraForge Adesha — Supervised Shadow Pilot Evaluation Guide
+## Benchmarking Autonomous Finance AI Against Historical Accounts Payable Records
 
-> **Document Type**: Proposed Enterprise Pilot Specification  
-> **Status**: Proposed Pilot Protocol (Not evidence of an active commercial customer deployment)  
+> **Document Type**: Enterprise Pilot Specification  
+> **System Under Evaluation**: MudraForge Adesha (Autonomous Finance AI)  
+> **Open Trust Anchor**: `@mudraforge/statutory` (MIT Zero-Dependency Substrate)  
+> **Execution Mode**: Supervised Read-Only Shadow Execution (Archival AP Records)  
 > **Target Audience**: Chief Financial Officers (CFOs), Heads of Tax, Accounts Payable Directors, Enterprise Risk Officers  
 
 ---
 
-## 1. Context & Purpose
+## 1. Executive Context & Purpose
 
-This document outlines a proposed, non-invasive evaluation protocol for enterprise finance teams seeking to assess the statutory accuracy and audit capabilities of MudraForge Adesha.
+This document specifies the protocol for conducting a **Supervised Shadow Pilot** of MudraForge Adesha within an enterprise finance department.
 
-A core operational challenge in corporate finance operations is ensuring consistent adherence to complex statutory withholding regimes, cumulative financial-year threshold tracking, and commercial delayed-payment regulations without disrupting active business operations. 
+In high-consequence corporate finance, autonomous systems must establish empirical accuracy and deterministic reliability before receiving operational authority. Modern accounts payable operations face immense regulatory pressure across direct tax withholding (TDS/TCS), commercial delayed payment laws (MSMED Act, Section 43B(h)), and evolving statutory transitions (the transition from the Income-tax Act, 1961 to the Income-tax Act, 2025). Human AP clerks and rigid rule engines frequently make systematic errors on cumulative thresholds, gross vs. basic tax bases, and legislative sunset dates.
 
-This proposed pilot enables an organization to test MudraForge's deterministic statutory engine against **historical, customer-approved accounts payable records** in a strictly read-only, advisory setting before considering any live workflow integration.
+MudraForge Adesha is an autonomous finance AI engineered to govern end-to-end accounts payable workflows. Rather than requesting live operational authority on day one, Adesha is evaluated in a **supervised shadow mode** against historical, customer-approved accounts payable datasets. 
 
----
+In this mode, Adesha reconstructs past vendor invoices, line items, and payment cycles in read-only memory, compares its deterministic legal determinations and simulated double-entry journal postings against the enterprise's historical enterprise resource planning (ERP) ledger entries, and generates an audit-grade reconciliation report highlighting variances, compliance risks, and cash-flow exposures.
+
+### The Role of the Open Trust Anchor (`@mudraforge/statutory`)
+A foundational risk in applying AI to enterprise finance is the hazard of ungrounded generative hallucinations. Adesha addresses this through architectural decoupling:
+- **Autonomous Reasoning & Governance (Adesha Proprietary Platform)**: Ingests unstructured invoices, interprets complex scopes of work, arbitrates commercial discrepancies, and formulates payment authorization leases.
+- **Deterministic Statutory Substrate ([`@mudraforge/statutory`](https://www.npmjs.com/package/@mudraforge/statutory))**: An open-source, zero-dependency legal knowledge format (OKF v0.2) and deterministic mathematical engine. All statutory determinations, cumulative thresholds, and tax formulas are calculated deterministically. Enterprise tax counsel and internal audit teams can inspect, verify, and run this substrate locally on-premise without external network communication.
 
-## 2. Pilot Objective
+---
 
-The primary objective of the proposed pilot is to evaluate historical vendor transactions against machine-readable statutory baselines to identify potential discrepancies in:
-1. **Withholding Tax (TDS) Classification**: Proper categorization under Section 194C (Contractors: 1% individual vs. 2% company), Section 194J (Technical Services 2% vs. Professional 10%), Section 194I (Rent: 2% machinery vs. 10% land/building), and Section 194H (Commission: 2% post-October 2024 vs. 5% prior).
-2. **Cumulative FY Threshold Handling**: Verifying whether cumulative vendor payments properly triggered statutory deduction gates upon crossing legal limits (e.g., Section 194Q ₹50 Lakhs excess, Section 194C ₹1 Lakh aggregate / ₹30,000 single bill).
-3. **GST Unbundling Adherence**: Checking whether withholding tax was deducted strictly on basic contract value or incorrectly calculated on gross invoice amounts including separately stated GST (CBDT Circular No. 23 of 2017).
-4. **Legislative Sunset Adherence**: Confirming that seller TCS under Section 206C(1H) was not applied to transactions post-1 April 2025.
-5. **MSME Delayed Payment Compliance**: Flagging payments to verified Micro and Small enterprises exceeding 15 days (oral) or 45 days (written agreement) under Sections 15 and 16 of the MSMED Act, 2006, along with associated Section 43B(h) disallowance risks.
+## 2. Core Pilot Objectives
+
+The Supervised Shadow Pilot benchmarks Adesha's autonomous decision-making against settled historical records across five primary compliance domains:
+
+1. **Withholding Tax (TDS/TCS) Classification & Rate Application**:
+   - Proper section categorization: Section 194C (Contractors: 1% individual vs. 2% company), Section 194J (Technical Services 2% vs. Professional 10%), Section 194I (Rent: 2% machinery vs. 10% land/building), and Section 194H (Commission: 2% post-October 2024 vs. 5% prior).
+   - Higher rate withholding for non-filers under Section 206AB (pre-1 April 2025) and invalid/inoperative PANs under Section 206AA (20% flat).
+2. **Cumulative Financial-Year Threshold & Excess Math**:
+   - Verification of cumulative purchase gates under Section 194Q: ensuring withholding is calculated strictly on the incremental purchase value exceeding ₹50 Lakhs within the financial year, rather than the entire invoice amount.
+   - Aggregate contractor thresholds under Section 194C (single invoice > ₹30,000 or aggregate > ₹1,00,000).
+3. **GST Basic Value Unbundling Adherence**:
+   - Verifying adherence to CBDT Circular No. 23 of 2017: confirming withholding was applied strictly to the basic taxable value and not computed on gross invoice totals inclusive of separately itemized CGST, SGST, or IGST.
+4. **Legislative Sunsets & Dual-Act Temporal Crystallization**:
+   - Confirming that seller TCS under Section 206C(1H) was omitted for transactions on or after 1 April 2025.
+   - Governing withholding crystallization by the earlier-event rule (earlier of credit in books or payment disbursement), correctly distinguishing between the Income-tax Act, 1961 and the Income-tax Act, 2025 (effective 1 April 2026).
+5. **MSME Delayed Payment Compliance & Section 43B(h)**:
+   - Tracking statutory payment clocks under Sections 15 and 16 of the MSMED Act, 2006 (15 days for unwritten terms, maximum 45 days for written agreements).
+   - Flagging compound interest liabilities at three times the RBI repo rate and identifying disallowance risks under Section 43B(h) of the Income-tax Act for amounts unpaid to Micro and Small suppliers at fiscal year-end, while applying the statutory trader exclusion (Office Memorandum 2/1(5)/2021).
 
 ---
 
-## 3. Proposed Candidate Inputs & Progressive Staging
+## 3. Candidate Ingestion Schema & Phased Staging
 
-To minimize operational effort for the customer's finance team, the proposed evaluation follows a staged approach:
+To minimize operational demands on enterprise accounting personnel, the pilot follows a two-stage progressive protocol:
 
-- **Stage 1 (Initial Calibration Sample — 30 to 50 Invoices)**: Begin with a targeted, representative sample of 30 to 50 historical invoices with known deduction outcomes and supporting records. This verifies column mappings, confirms ingestion formatting, and calibrates baseline rules with minimum time investment from the client.
-- **Stage 2 (Expanded Audit — 200 to 500 Invoices)**: Once the workflow, field mapping, and review protocols are established in Stage 1, the evaluation can expand to a full quarter's volume (200 to 500 records) to assess broad cumulative thresholds (such as Section 194Q and 194C cumulative annual limits).
+### Phase 1: Calibration & Field Alignment (30 to 50 Historical Invoices)
+A representative batch of 30 to 50 settled vendor invoices with known tax and payment outcomes is ingested. This phase validates data field mappings, verifies vendor classification schemas, and establishes baseline reconciliation rules with negligible customer effort.
 
-To perform the evaluation, the customer provides an export (CSV or structured tabular extract) containing the following fields:
+### Phase 2: Comprehensive Historical Shadow Benchmark (200 to 500 Historical Invoices)
+Following Phase 1 calibration, the evaluation expands to a full quarter's transaction volume (200 to 500 invoices). This volume enables robust validation of cumulative vendor spend thresholds (Section 194Q, Section 194C) and multi-month MSME payment clock tracking.
 
-| Field Group | Required Parameters | Purpose in Evaluation |
+### Data Ingestion Parameters
+The customer provides an archival tabular export (CSV, XLSX, or JSON extract) containing the following fields:
+
+| Field Group | Required Parameters | Analytical Purpose in Shadow Pilot |
 | :--- | :--- | :--- |
-| **Transaction Metadata** | Invoice Number, Invoice Date, Booking Date | Evaluates temporal validity and applicable legislative regime (1961 Act vs. 2025 Act). |
-| **Vendor Identity** | Vendor Legal Name, Entity Type (Individual, Firm, Co.), Vendor PAN, GSTIN | Determines applicable rate schedules (e.g. 1% vs 2% under 194C; 20% under 206AA if PAN missing). |
-| **Financial Values** | Basic Taxable Amount, CGST, SGST, IGST, Total Invoice Gross Amount | Verifies basic-value unbundling vs. gross withholding. |
-| **Statutory Classification** | Line-item expense description, historical TDS section applied, historical TDS amount deducted | Compares historical treatment against engine ground truth. |
-| **Settlement Dates** | Payment / Clearance Date, Payment Method | Measures settlement timelines against the MSMED statutory payment clock. |
-| **Enterprise Attributes** | Vendor MSME Registration Type (Micro, Small, Medium, Trader), Udyam Number (if on file) | Filters MSME delayed-payment rules (applying trader exclusion under OM 2/1(5)/2021). |
+| **Transaction Metadata** | Invoice Number, Invoice Date, ERP Booking Date | Establishes temporal validity, accounting credit timestamp, and legislative regime. |
+| **Vendor Identity** | Vendor Legal Name, Entity Type (Individual, LLP, Corporate), Vendor PAN, GSTIN | Determines applicable statutory rate tiers, corporate status, and Section 206AA rate penalties. |
+| **Financial Values** | Basic Taxable Amount, Itemized CGST, SGST, IGST, Total Gross Invoice Value | Assesses adherence to GST unbundling standards vs. gross withholding. |
+| **Historical ERP Classification** | Line-item description, historical TDS section applied, historical TDS amount withheld | Benchmarks human/ERP decisions against Adesha's deterministic statutory engine. |
+| **Settlement Details** | Payment / Bank Clearance Date, Historical Payment Method, Bank UTR (if recorded) | Measures settlement intervals against MSMED Act statutory clocks. |
+| **Vendor Master Attributes** | MSME Registration Category (Micro, Small, Medium, Trader), Udyam Number (if on file) | Drives MSME statutory interest calculations and Section 43B(h) disallowance risk analysis. |
 
 ---
 
-## 4. Processing Workflow & Exception Handling
+## 4. Adesha Shadow Execution Pipeline
 
-The evaluation runs as an offline, non-intrusive batch process:
+The Supervised Shadow Pilot operates entirely offline as a non-intrusive analytical pipeline:
 
 ```
-[Customer AP Extract] ──► Input Validation ──► Statutory Rule Engine ──► Discrepancy Analysis ──► Human Review Gate
-                                                                                                    ↓
-                                                                                        [Advisory Audit Report]
+[Customer Archival AP Extract]
+              │
+              ▼
+┌────────────────────────────────────────┐
+│  Phase 1: Ingestion & Input Validation │
+│  - Field schema verification           │
+│  - Tax identifier syntax validation    │
+└────────────────────────────────────────┘
+              │
+              ▼
+┌────────────────────────────────────────┐
+│  Phase 2: Semantic Reasoning & Parsing │
+│  - Scope of work analysis              │
+│  - Contractual term classification     │
+└────────────────────────────────────────┘
+              │
+              ▼
+┌────────────────────────────────────────┐
+│  Phase 3: Deterministic Grounding      │
+│  (@mudraforge/statutory)               │
+│  - Cumulative FY threshold evaluation  │
+│  - Statutory withholding rate derivation│
+│  - MSMED 15/45-day clock calculation   │
+└────────────────────────────────────────┘
+              │
+              ▼
+┌────────────────────────────────────────┐
+│  Phase 4: Simulated AP Orchestration   │
+│  - Single-use payment lease derivation │
+│  - Double-entry ERP journal simulation │
+└────────────────────────────────────────┘
+              │
+              ▼
+┌────────────────────────────────────────┐
+│  Phase 5: Reconciliation & Variance    │
+│  - Delta analysis vs. historical ERP   │
+│  - Fail-closed ambiguity isolation     │
+└────────────────────────────────────────┘
+              │
+              ▼
+[Advisory Discrepancy & Verification Report]
 ```
 
-### The Human-in-the-Loop Ambiguity Standard
-In real-world finance operations, certain vendor invoices present legal ambiguities that cannot be resolved from numbers alone (e.g., mixed composite contracts involving both equipment supply and installation labour).
+### The Fail-Closed Ambiguity Standard
+In corporate finance, certain transactions contain contractual ambiguities that cannot be resolved solely from ledger metadata (for example, composite contracts spanning both equipment hardware supply and specialized engineering services).
 
-- **Explicit Fail-Closed Policy**: The evaluation engine does not guess or force an arbitrary classification on ambiguous transactions.
-- **Flagged Review Categories**: When input data lacks sufficient granularity (such as missing scope-of-work documentation or ambiguous GST itemization), the system categorizes the record as `REQUIRES_HUMAN_REVIEW` with an explicit note explaining the legal assumption required.
+- **Strict Fail-Closed Policy**: Adesha does not generate arbitrary tax assumptions or probabilistic guesses on ambiguous transactions.
+- **Flagged Review Categories**: When archival data lacks necessary granularity (such as missing scope-of-work documentation or unbundled tax breakdowns), Adesha categorizes the item as `REQUIRES_HUMAN_REVIEW` accompanied by an explicit legal justification detailing the evidentiary prerequisite.
 
 ---
 
-## 5. Pilot Deliverables
+## 5. Pilot Deliverables & Tri-Part Variance Classification
+
+At the conclusion of the evaluation, the enterprise finance leadership receives a comprehensive **Advisory Accounts Payable Discrepancy & Verification Report** comprising:
 
-At the conclusion of the evaluation, the customer receives an **Advisory Accounts Payable Discrepancy & Verification Report** comprising:
+### 1. Executive Summary
+- Total transaction count evaluated vs. records with complete statutory determinability.
+- Aggregate count and value of historical transactions matching statutory baseline.
+- Aggregate count and value of identified statutory variances and compliance risks.
 
-1. **Executive Findings Summary**:
-   - Total records evaluated vs. records with complete statutory determinability.
-   - Aggregate count of matched historical treatments.
-   - Aggregate count of flagged statutory variances.
-2. **Detailed Discrepancy Register (Tri-Part Classification)**:
-   Findings are strictly classified into three distinct categories to avoid premature legal assumptions:
-   - **Category A — Confirmed Calculation Differences**: Mathematical or rounding discrepancies on settled statutory rates, unbundled GST arithmetic, or clearly crossed financial thresholds.
-   - **Category B — Potential Statutory Discrepancies**: Inconsistent rates or threshold treatments where all input facts (PAN, entity type, invoice date) appear complete on the face of the record.
-   - **Category C — Items Requiring External Documentation Verification**: Apparent rate differences that may be legally justified by unrecorded external documents (e.g. an Assessing Officer certificate for lower deduction under Section 197, a Section 194C(6) goods transporter ownership declaration, or an MSME trader NIC classification exclusion). The report flags these as *verification checkpoints* rather than claiming a tax error.
-3. **Statutory Audit Trail**:
-   - For every flagged variance: the exact governing statute, applicable section code, official Gazette citation, and relevant CBDT/CBIC executive circular.
-4. **Unresolved Assumptions Log**:
-   - Comprehensive inventory of records requiring internal company tax counsel determination.
+### 2. Tri-Part Variance Classification Register
+To provide actionable clarity without premature legal assumptions, all identified variances are categorized into three distinct classes:
 
-> **Important Commercial Notice**: The pilot report is strictly analytical and advisory. MudraForge does not guarantee that a pilot will discover historical errors, recoverable tax sums, or cash savings; the value of the evaluation is establishing an empirical baseline of compliance consistency.
+- **Category A — Confirmed Calculation & Threshold Variances**:
+  Direct mathematical, rounding, or threshold calculation errors on settled law. Examples include withholding tax deducted on gross invoice totals instead of net basic amounts, or Section 194Q applied to the full invoice rather than the excess over ₹50 Lakhs.
+- **Category B — Statutory Rate & Classification Discrepancies**:
+  Inconsistent statutory classifications where all transaction attributes (PAN, entity type, invoice date) are complete on the face of the record. Examples include applying Section 194C (2%) to professional services governed by Section 194J (10%), or applying Section 206C(1H) post-sunset.
+- **Category C — Documentation Verification Checkpoints**:
+  Instances where historical treatment differed from statutory defaults but may be legally substantiated by external documents not present in the tabular ledger. Examples include lower-withholding certificates issued under Section 197, goods transporter declarations under Section 194C(6), or MSME trader NIC classification exclusions. These items are presented as *verification checkpoints* for internal tax counsel rather than asserting non-compliance.
 
-### What the Proposed Pilot Demonstrates vs. What It Cannot Establish
+### 3. Statutory Audit Trail
+Every identified variance includes direct, canonical citations to the governing statute, section number, official Gazette notification, and relevant CBDT/CBIC executive circular.
 
-| What the Pilot Can Demonstrate | What It Cannot Establish by Itself |
+### 4. Shadow Double-Entry Journal Reconciliation
+For every invoice, Adesha generates a simulated double-entry journal voucher (Debit Expense, Debit Input Tax, Credit Vendor Payable, Credit TDS Payable). This simulated voucher is compared against the historical ERP general ledger journal to highlight booking discrepancies.
+
+### Analytical Scope & Boundary Commitments
+
+| What the Supervised Shadow Pilot Demonstrates | What It Cannot Establish by Itself |
 | :--- | :--- |
-| The engine can process customer-supplied historical invoice extracts. | It can seamlessly ingest every ERP or arbitrary billing format without custom mapping. |
-| Calculations agree with independently verified tax outcomes on clear-cut cases. | Every statutory interpretation or tax deduction across all scenarios is legally infallible. |
-| Discrepancies and assumptions are fully traceable to primary gazette citations. | The client will necessarily achieve a specific financial saving or tax recovery. |
-| Repeat runs on the same input data produce mathematically identical results. | Production deployment readiness, real-time banking security, or live ERP integration. |
+| Adesha accurately parses and interprets historical AP extracts. | Instantaneous ingestion of proprietary ERP schemas without initial field mapping. |
+| Mathematical and statutory determinations strictly agree with independent tax ground truth. | Legal infallibility across non-standard or unresolved statutory litigation edge cases. |
+| Complete audit traceability from every recommendation to primary gazette citations. | Guaranteed immediate financial recovery or cash tax refunds. |
+| Repeat deterministic runs on identical archival inputs produce mathematically identical results. | Production-grade real-time banking security or live ERP multi-region high availability. |
 
 ---
 
-## 6. Security, Confidentiality & Data Handling
+## 6. Security, Confidentiality & Data Protection
 
-> **Confidentiality Note on Historical Data**: Historical accounts payable records are not zero-risk. Invoices contain confidential supplier identities, commercial pricing structures, PANs, and banking metadata. Running locally or within customer-designated infrastructure minimizes external exposure, but strict data handling, field masking, and deletion agreements remain mandatory prerequisites before transferring any real records.
+Corporate accounts payable records contain commercially sensitive supplier pricing, bank account details, and corporate tax identifiers. The Supervised Shadow Pilot adheres to strict security protocols:
 
-To protect enterprise data, the pilot protocol defines clear operational boundaries:
+### Baseline Execution Boundaries
+- **On-Premise / Private Cloud Execution**: The pilot engine and open `@mudraforge/statutory` substrate can run entirely within the enterprise's private network or local workstation environment with zero external data egress.
+- **Strictly Read-Only Ingestion**: Adesha accesses only the historical extract provided by the customer. It possesses zero programmatic access to active ERP systems, production databases, or banking networks.
 
-### Verified Baseline Capabilities
-- **Local / On-Premise Execution Option**: The core evaluation engine and statutory commons can execute locally within the customer's designated environment with zero external network connectivity.
-- **Read-Only Scope**: The evaluation accesses only historical records provided by the customer. It contains no programmatic write access to the customer's ERP, general ledger, or banking infrastructure.
-
-### Pilot Prerequisites (To Be Agreed in Writing Prior to Initiation)
-Prior to transferring any sample data or initiating evaluation scripts, the parties will establish:
-1. **Bilateral Non-Disclosure Agreement (NDA)**: Governing proprietary financial and supplier pricing data.
-2. **Customer-Side Field Masking / Anonymization**: The customer may optionally hash or mask sensitive fields (such as bank account numbers or internal vendor IDs) prior to transmission.
-3. **Data Retention & Disposal Schedule**: Agreement on secure disposal of evaluation extracts within a defined period (e.g., 30 days post-report delivery).
-4. **Environment Specification**: Mutual agreement on whether processing occurs on customer-controlled workstations or a private cloud environment.
+### Information Governance Protocols
+Prior to ingesting customer records, standard enterprise safeguards are established:
+1. **Bilateral Non-Disclosure Agreement (NDA)**: Protecting all vendor commercial terms, volume discounts, and operational financial metrics.
+2. **Customer-Side Pseudonymization**: The enterprise may hash or redact sensitive identifiers (such as bank account numbers or internal vendor keys) prior to transmission.
+3. **Data Disposal Mandate**: Certified cryptographic deletion of all evaluation datasets upon delivery and acceptance of the final audit report.
 
 ---
 
-## 7. Strict Operational Boundaries
+## 7. Strict Operational Safeguards
 
-To prevent operational ambiguity, the boundaries of this proposed pilot are explicitly defined:
+To maintain clear enterprise governance, the pilot operates under absolute operational restrictions:
 
-- **No Live Ledger Mutations**: The pilot will not post journal entries, alter general ledger balances, or modify vendor records in the customer's accounting system (SAP, Zoho Books, Tally, NetSuite).
-- **No Money Movement**: The pilot does not connect to banking APIs, issue payment orders, or disburse funds.
-- **No Regulatory Filing**: The pilot does not generate or submit Form 26Q returns or TDS challans to the Income Tax Department.
-- **Not Formal Legal Advice**: Deliverables constitute technical compliance analysis and do not replace legal opinions from the customer's statutory tax auditors or legal counsel.
+- **Zero Live Ledger Mutations**: Adesha will not write back journals, alter vendor balances, or modify general ledger accounts in SAP, Zoho Books, NetSuite, Oracle, or Tally.
+- **Zero Banking Rail Access**: Adesha does not connect to corporate banking APIs, initiate wire transfers, or hold authority to disburse funds.
+- **Zero Regulatory Submissions**: Adesha will not generate or transmit Form 26Q quarterly returns or TDS challans to government portals.
+- **Technical Advisory Designation**: All deliverables constitute technical compliance analysis and do not replace formal legal or statutory audit opinions from certified enterprise tax counsel.
 
 ---
 
-## 8. Success & Evaluation Criteria
+## 8. Quantitative Evaluation & Acceptance Benchmarks
 
-Before initiating a pilot, both parties agree to measurable evaluation benchmarks:
+The success of the Supervised Shadow Pilot is measured against objective, pre-agreed quantitative benchmarks:
 
-| Criterion | Definition | Evaluation Metric |
+| Evaluation Benchmark | Objective Definition | Success Threshold |
 | :--- | :--- | :--- |
-| **Input Completeness** | Sufficiency of customer data to determine statutory applicability | Percentage of records with complete necessary fields ($\ge 90\%$ target) |
-| **Calculation Accuracy** | Agreement on clear-cut cases governed by settled law | $100\%$ mathematical and threshold agreement on verified records |
-| **Ambiguity Handling** | Clean separation of uncertain cases without hallucinated conclusions | $100\%$ of incomplete or composite records flagged for human review |
-| **Statutory Traceability** | Every variance cited to primary gazette or executive circular | $100\%$ citation resolution to official government sources |
-| **Audit Reproducibility** | Repeated runs across the same dataset produce identical outputs | Zero variance across repeat deterministic runs |
+| **Input Completeness** | Proportion of archival records with sufficient parameters to evaluate statutory applicability | $\ge 90\%$ of provided dataset |
+| **Calculation Accuracy** | Agreement with settled statutory ground truth on unambiguous records | $100\%$ precision on verified provisions |
+| **Ambiguity Isolation** | Strict fail-closed categorization of records lacking necessary documentation | $100\%$ isolation of uncertain records |
+| **Citation Traceability** | Traceability of every flagged variance to deep primary government endpoints | $100\%$ verified canonical citations |
+| **Deterministic Reproducibility** | Mathematical identity across repeat runs on the same input dataset | Zero variance across repeated runs |
 
 ---
 
-## 9. Initiating a Pilot Discussion
+## 9. Initiating a Supervised Shadow Pilot
+
+To schedule an architecture review, receive sample ingestion schemas, or coordinate a Supervised Shadow Pilot for your finance organization:
 
-To discuss a proposed historical AP evaluation, review sample schema formats, or coordinate data requirements:
-- **Email**: [hello@mudraforge.in](mailto:hello@mudraforge.in) or [support@mudraforge.in](mailto:support@mudraforge.in)
+- **Enterprise Inquiries**: [hello@mudraforge.in](mailto:hello@mudraforge.in) or [support@mudraforge.in](mailto:support@mudraforge.in)
 - **Direct Founder Contact**: Mondeep Engti at [mondeepe@gmail.com](mailto:mondeepe@gmail.com)
-- **Official Documentation**: [https://mudraforge.in/docs](https://mudraforge.in/docs)
+- **Technical Architecture Documentation**: [https://mudraforge.in/docs](https://mudraforge.in/docs)
+- **Open Trust Anchor Repository**: [https://github.com/mondeep0123/mudraforge-statutory](https://github.com/mondeep0123/mudraforge-statutory)

package/docs/PROVENANCE.md

@@ -8,17 +8,17 @@ This document records the cryptographic provenance, normative specifications, an
 
 | Item | Value |
 |---|---|
-| **Package Release** | **`v2.8.1`** (Stable Patch Release) |
+| **Package Release** | **`v2.9.0`** (Production Release) |
 | **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`](./CORPUS_QUALITY.md) |
+| **Corpus Quality Card** | 100% Primary Citation Resolution (76/76 URLs verified; 108 citations across 29 provisions) in [`docs/CORPUS_QUALITY.md`](./CORPUS_QUALITY.md) |
 | **Architecture Decision Records** | 6 Normative ADRs documented in [`docs/ARCHITECTURE_DECISIONS.md`](./ARCHITECTURE_DECISIONS.md) |
 | **Vendor Conformance Suite** | 12/12 Passing Fixture Tests in [`conformance/`](../conformance/) |
 | **End-to-End Execution Trace** | Audited 7-stage AP lifecycle in [`examples/`](../examples/) (`npm run example:trace`) |
 | **Enterprise Assurance Preview** | Formal TLA+ & mutation defenses in [`docs/ADESHA_ASSURANCE_OVERVIEW.md`](./ADESHA_ASSURANCE_OVERVIEW.md) |
-| **Integrity Root** | SHA-256 root manifest in [`okf/manifest.json`](../okf/manifest.json) (reproducible byte-level non-tampering proof) |
+| **Integrity Root** | SHA-256 root manifest in [`okf/manifest.json`](../okf/manifest.json) (`sha256-4bbe36c3db841b833dd2bebbd6c1c5ed735498e7b20d1221c323ceb211529fe0` across 86 files) |
 | **Temporal Framework** | Dual-Act Bridge: *Income-tax Act, 1961* & *Income-tax Act, 2025* |
-| **Verification Gate** | 100% Pass across cumulative thresholds, legislative sunsets, and excess math |
+| **Verification Gate** | 100% Pass across all 80 test suites (cumulative thresholds, legislative sunsets, and excess math) |
 
 ---
 

package/docs/VERIFICATION.md

@@ -1,9 +1,9 @@
 # @mudraforge/statutory: Verification & Conformance Report
 
-> **Audited Package**: `@mudraforge/statutory` v2.4.0 (Public Open Knowledge Commons)  
+> **Audited Package**: `@mudraforge/statutory` v2.9.0 (Public Open Knowledge Commons)  
 > **Target Runtime**: Node.js v20+, Bun, Deno, Cloudflare Workers  
-> **Public Test Status**: 24 Public Conformance & Verification Suites Passing (100% Reproducible)  
-> **Cryptographic Scope**: SHA-256 Merkle root digest over 25 bundled knowledge files (0 mismatches)  
+> **Public Test Status**: 80 Multi-Domain Regression & Verification Suites Passing (100% Reproducible)  
+> **Cryptographic Scope**: SHA-256 Merkle root digest over 86 bundled knowledge files (0 mismatches)  
 
 ---
 
@@ -90,17 +90,17 @@ The conformance runner (`conformance/test_conformance.js`) tests parser behavior
 
 ## 6. Reproducible Release Tarball Verification
 
-Every published release tarball can be independently verified against Git tag `v2.4.0`:
+Every published release tarball can be independently verified against Git tag `v2.9.0`:
 
 ```bash
 # 1. Pack the distribution tarball
 npm pack
 
 # 2. Compute the SHA-256 checksum of the tarball (PowerShell)
-Get-FileHash mudraforge-statutory-2.4.0.tgz -Algorithm SHA256
+Get-FileHash mudraforge-statutory-2.9.0.tgz -Algorithm SHA256
 
 # Or in Linux / macOS:
-# sha256sum mudraforge-statutory-2.4.0.tgz
+# sha256sum mudraforge-statutory-2.9.0.tgz
 ```
 
-The resulting package contains exactly 48 audited files (zero extraneous build artifacts, zero internal development scripts).
+The resulting package contains exactly 124 audited files (zero extraneous build artifacts, zero internal development scripts).

package/okf/manifest.json

@@ -1,6 +1,6 @@
 {
   "okfVersion": "2.9.0",
-  "publishedAt": "2026-10-26T08:10:43.979Z",
+  "publishedAt": "2026-10-26T21:03:27.210Z",
   "rootHash": "sha256-4bbe36c3db841b833dd2bebbd6c1c5ed735498e7b20d1221c323ceb211529fe0",
   "totalSections": 29,
   "totalFiles": 86,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mudraforge/statutory",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "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",
@@ -11,6 +11,16 @@
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./outcomes": {
+      "types": "./types/index.d.ts",
+      "import": "./src/outcomes.js",
+      "default": "./src/outcomes.js"
+    },
+    "./constants": {
+      "types": "./types/index.d.ts",
+      "import": "./src/constants.js",
+      "default": "./src/constants.js"
+    },
     "./calculators": {
       "types": "./types/index.d.ts",
       "import": "./src/calculators.js",
@@ -22,6 +32,12 @@
     "*": {
       "calculators": [
         "./types/index.d.ts"
+      ],
+      "outcomes": [
+        "./types/index.d.ts"
+      ],
+      "constants": [
+        "./types/index.d.ts"
       ]
     }
   },
@@ -30,6 +46,7 @@
   },
   "sideEffects": false,
   "bin": {
+    "statutory": "bin/cli.js",
     "mudraforge-statutory": "bin/cli.js"
   },
   "files": [

package/src/constants.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Canonical Single-Source-of-Truth Constants for @mudraforge/statutory.
+ * Pure ESM module with zero Node.js/browser-specific dependencies.
+ * Safe to import across Node.js, Cloudflare Workers, browsers, and Edge runtimes.
+ *
+ * @license MIT
+ */
+
+export const STATUTORY_CLIENT_VERSION = '2.10.0';
+export const DEFAULT_BASE_URL = 'https://api.mudraforge.in';