@mudraforge/statutory 2.13.0 → 2.14.0

package/docs/OKF_MAINTENANCE_SOP.md

@@ -1,286 +0,0 @@
-# OKF Statutory Profile: Maintenance Standard Operating Procedure (SOP)
-
-> **Document Version**: 1.1.0  
-> **Classification**: Normative Engineering & Release Governance Standard  
-> **Target Substrate**: `@mudraforge/statutory` & Adesha Governance Runtime  
-> **Base Specification**: Open Knowledge Format (OKF) v0.2 (Upstream Google Specification)  
-> **Extension Profile**: MudraForge Statutory Knowledge Profile v0.2  
-
----
-
-## 1. Purpose, Authority & Governance Boundary
-
-This Standard Operating Procedure (SOP) establishes the mandatory release discipline, authoring conventions, citation standards, cryptographic integrity controls, and verification protocols for the MudraForge Statutory Knowledge Substrate (`@mudraforge/statutory`).
-
-### 1.1 Release Control vs. Legal Correctness
-This SOP functions as a **reproducible release control and engineering quality discipline**, not as proof of absolute statutory correctness or judicial finality:
-- Passing all tests establishes conformance to the **tested requirements, mathematical formulas, and documented edge cases**. It does not independently prove that every legal interpretation is infallible or that government citations will remain valid indefinitely.
-- In accordance with regulatory AI governance principles—such as those articulated in the Reserve Bank of India (RBI) 2025 FREE-AI Committee Report (*Free and Responsible Exploration of AI in Finance*)—automated toolkits, deterministic validators, and algorithmic guardrails exist to support institutional risk management, auditability, and validation. They are **decision-support controls**, never legal or statutory substitutes for an enterprise's own fiduciary governance, internal financial controls, or qualified tax counsel.
-
-### 1.2 Target Failure Modes
-This SOP is enforced to systematically prevent:
-1. **Link Rot & Citation Drift**: Broken government URLs that degrade external inspectability and audit confidence.
-2. **Behavioral & Calculator Drift**: Discrepancies between deterministic code calculators, LLM prompt directives, and primary legislative truth.
-3. **Rollback, Replay & Tamper Vulnerabilities**: Malicious substitution, stale bundle replay, or unauthorized manipulation of statutory rules.
-4. **Sub-Domain Collisions**: Heuristic false matches between single-digit or composite statutory sections (e.g. Section 8, Section 9(3), Section 194C).
-
----
-
-## 2. Upstream OKF Specification vs. MudraForge Statutory Profile
-
-To preserve architectural clarity, this standard strictly distinguishes between upstream Open Knowledge Format (OKF) conformance and MudraForge's additional statutory engineering profile:
-
-```mermaid
-flowchart TD
-    subgraph UPSTREAM["Upstream Google OKF v0.2 (Minimal & Portable)"]
-        direction TB
-        OKF_MD["Markdown Semantic Documentation"]
-        OKF_YAML["YAML Frontmatter Metadata (id, title, authority, dates)"]
-        OKF_DIR["Hierarchical Folder Structure by Regulatory Domain"]
-    end
-
-    subgraph PROFILE["MudraForge Statutory Profile (Engineering Extension)"]
-        direction TB
-        MF_JSON["section.json: Typed Machine Contracts & Formula ASTs"]
-        MF_CALC["Universal Statutory Virtual Machine (src/usvm/evaluation_vm.js)"]
-        MF_HASH["SHA-256 Merkle Tree Integrity Manifests (okf/manifest.json)"]
-        MF_SIG["Ed25519 Release Pinning & Tamper-Evident Signatures"]
-        MF_FAIL["Fail-Closed Missing Evidence & Contradiction Gates"]
-    end
-
-    UPSTREAM -->|Inherited By| PROFILE
-```
-
-### 2.1 Upstream OKF Conformance
-Upstream Google OKF is a lightweight, portable knowledge representation designed for cross-agent interchange. It standardizes:
-- Markdown-based legal narratives with structured YAML frontmatter.
-- Hierarchical folder trees organized by regulatory jurisdiction and domain.
-- Self-contained, portable knowledge artifacts that can be ingested by any LLM or knowledge base.
-
-*Upstream OKF does NOT prescribe a specific calculation engine, machine-readable JSON schema, cryptographic release pipeline, or transactional runtime.*
-
-### 2.2 The MudraForge Statutory Profile
-The MudraForge Statutory Profile introduces additional normative engineering conventions on top of OKF to enable high-assurance financial automation:
-- **Typed Machine Contracts (`section.json`)**: Eliminates heuristic interpretation of numeric thresholds, currency values, and applicability conditions.
-- **Deterministic Computation**: All threshold comparisons, tax rates, excess math, and rounding execute through deterministic code on CPU (zero LLM token generation for numbers).
-- **Cryptographic Release Verification**: SHA-256 Merkle trees and Ed25519 digital signatures guarantee byte-level non-tampering from edge to endpoint.
-- **Fail-Closed Evidence Gates**: Rejection or quarantine of transactions when statutory evidence is incomplete, unverified, or contradictory.
-
----
-
-## 3. Architectural Separation & Testable Guarantees
-
-Every statutory provision in the MudraForge profile maintains a strict division of responsibility across three distinct artifact types:
-
-```mermaid
-flowchart TD
-    subgraph ARTIFACTS["OKF Provision Directory: okf/<domain>/<statute_folder>/"]
-        SJ["section.json<br/>(Machine Contract)"]
-        CB["circulars/*.md<br/>(Semantic Executive Briefs)"]
-        FS["forms/*.json | forms/*.md<br/>(Filing Schemas & Templates)"]
-    end
-
-    subgraph ENGINE["Universal Statutory Virtual Machine (USVM)"]
-        SJ --> USVM["USVM Declarative Kernel<br/>• Declarative AST Execution<br/>• Rational BigInt Paisa Math<br/>• Fiduciary Invariant Gate"]
-    end
-
-    subgraph REASONING["Adesha Governance Layer (LLM + Human)"]
-        CB --> LLM["Agent Reasoning<br/>• Context Synthesis<br/>• Exception Analysis<br/>• Discrepancy Detection"]
-        CB --> AUDIT["External Tax Counsel<br/>• Independent Verification<br/>• Audit Trails"]
-    end
-
-    subgraph WRITEBACK["Compliance Systems"]
-        FS --> ERP["ERP Integration<br/>• Form 26Q, GSTR-3B, MSME-1"]
-    end
-```
-
-### 3.1 Testable Guarantees
-Rather than making unprovable claims of "zero hallucination", the MudraForge profile operates under four testable and verifiable guarantees:
-
-1. **Deterministic Execution**: Calculations execute exclusively through deterministic code. Given identical inputs, rules, and effective dates, the resulting tax calculations, cumulative thresholds, and paisa rounding are mathematically invariant across all runs.
-2. **Versioned Applicability**: Legal applicability is evaluated against versioned rules, notified effective dates, and explicit statutory sunset boundaries (e.g. Section 206C(1H) sunset on 1 April 2025; Section 393 effective 1 April 2026).
-3. **Fail-Closed Handling of Uncertainty**: Missing, incomplete, or contradictory evidence triggers a fail-closed outcome (holding payments, flagging discrepancies, or requesting missing links) rather than manufacturing assumptions.
-4. **Independent Verification**: Test fixtures verify specified behaviors, edge cases, and arithmetic against independent statutory ground truth rather than trusting agent self-reports.
-
-### 3.2 Artifact Responsibilities
-
-| Artifact | Primary Consumer | Content Mandate | Operational Role |
-|---|---|---|---|
-| [`section.json`](../okf/direct_tax/tds_goods_194q/section.json) | **Deterministic Engine Runtime** | Typed numbers, effective dates, boolean applicability conditions, and threshold formulas. | Machine execution on CPU. Prevents mathematical drift, rate confusion, and arithmetic errors. |
-| `circulars/*.md` | **LLM Agents & Human Auditors** | Semantic legal context, executive interpretations, judicial precedents, and YAML frontmatter. | Cross-domain reasoning, statutory crosswalks, exception argumentation, and human auditability. |
-| `forms/*` | **Compliance & Reporting Systems** | Machine-evaluable JSON schemas and Markdown return checklists. | Return preparation, ERP writeback payloads, and statutory disclosure schedules. |
-
----
-
-## 4. Citation & Link Integrity Protocol
-
-To prevent link rot caused by frequent government portal redesigns and CMS migrations, OKF provisions must follow the **Dual-Tier URL Standard**:
-
-### 4.1 Tier 1: Canonical Authority Landing Pages
-Direct PDF download paths on government websites frequently change or break during CMS updates. Therefore, official citation URLs must point to canonical, evergreen regulatory landing pages:
-- **CBDT / Direct Tax Circulars**: `https://www.incometaxindia.gov.in/pages/communications/circulars.aspx`
-- **CBDT Notifications**: `https://www.incometaxindia.gov.in/pages/communications/notifications.aspx`
-- **Income-tax Act Provisions**: `https://www.incometaxindia.gov.in/pages/acts/income-tax-act.aspx`
-- **CBIC / GST Circulars & Notifications**: `https://taxinformation.cbic.gov.in/`
-- **MSME Policies & Office Memorandums**: `https://dcmsme.gov.in/` or `https://msme.gov.in/`
-- **MCA Notifications & Orders**: `https://www.mca.gov.in/`
-- **RBI Master Directions**: `https://www.rbi.org.in/`
-- **Supreme Court of India**: `https://sci.gov.in/`
-- **ICAI Standards & Guidance Notes**: `https://www.icai.org/`
-- **US Internal Revenue Service (IRS)**: `https://www.irs.gov/`
-
-### 4.2 Tier 2: Legal Instrument Metadata
-In `section.json`, the legal instrument itself must be fully described so that statutory provenance is preserved even in offline or air-gapped environments:
-```json
-{
-  "authority": "Central Board of Direct Taxes (CBDT)",
-  "instrument": "Circular No. 13 of 2021 (Dated 30 June 2021)",
-  "subject": "Guidelines under section 194Q of the Income-tax Act, 1961 - Threshold calculation & advance netting",
-  "officialUrl": "https://www.incometaxindia.gov.in/pages/communications/circulars.aspx"
-}
-```
-
-### 4.3 Domain Whitelist Enforcement
-All citation URLs must belong to the regulatory domain whitelist defined in [`scripts/verify_citation_links.js`](../scripts/verify_citation_links.js). Citations to commercial blogs, paywalled content aggregators, or unvetted third-party websites are prohibited.
-
-### 4.4 Protocol Security & TLS Trust
-- **100% HTTPS Enforcement**: Insecure `http://` links are rejected by the linter.
-- **Government PKI Recognition**: Automated link verification recognizes leaf certificates issued by the Government of India Controller of Certifying Authorities (CCA / NIC CA).
-
----
-
-## 5. The 10-Step Release Control Lifecycle
-
-Whenever authoring, updating, or amending a statutory provision, this 10-step quality discipline must be executed sequentially:
-
-```mermaid
-flowchart TD
-    S1["1. Legal Sourcing & Dual-Act Boundary"] --> S2["2. Author section.json"]
-    S2 --> S3["3. Author circulars/*.md"]
-    S3 --> S4["4. Author forms/* Schemas"]
-    S4 --> S5["5. Citation & Link Audit (npm run citations)"]
-    S5 --> S6["6. Linter & Schema Conformance (npm run validate)"]
-    S6 --> S7["7. Merkle Manifest Re-Gen (npm run manifest)"]
-    S7 --> S8["8. Client Pinning & Ed25519 Signing"]
-    S8 --> S9["9. Dual Regression Testing (Package + Engine)"]
-    S9 --> S10["10. SemVer Release & Distribution"]
-```
-
-### Step 1: Legal Sourcing & Dual-Act Temporal Boundary
-1. Identify primary legislation: Act name, Section number, notified effective date.
-2. Determine temporal classification:
-   - `ACTIVE`: Currently in force under current legislation.
-   - `SUNSET_SUPERSEDED`: Subject to statutory sunset (e.g. Section 206C(1H) on 1 April 2025).
-   - `FUTURE_LAW`: Enacted forward law (e.g. Income-tax Act, 2025 Section 393 on 1 April 2026).
-3. Author declarative AST package in `ast.json` evaluated by the Universal Statutory Virtual Machine (`src/usvm/evaluation_vm.js`).
-
-### Step 2: Author `section.json` Machine Contract
-- Declare mandatory fields: `sectionId`, `sectionCode`, `aliases`, `governingStatute`, `statutorySection`, `successorStatute`, `successorSection`, `title`, `effectivePeriod`, `plainTextSummary`, `keyStatutoryThresholds`, `officialCitations`, `requiredDocumentChecklist`, `tier`, `version`.
-- Standardize all search aliases in lowercase or official legal codes (e.g. `["194q", "sec194q", "tds goods"]`).
-
-### Step 3: Author Circulars (`circulars/*.md`)
-- Enforce strict YAML frontmatter (`id`, `title`, `authority`, `date`, `statutory_section`, `valid_from`, `valid_to`, `temporal_status`, `subject`, `official_url`).
-- Provide clear executive summaries detailing commercial application, tax base unbundling rules, and statutory exceptions.
-
-### Step 4: Author Compliance Forms (`forms/*`)
-- Supply machine-evaluable JSON schemas or Markdown checklists for compliance returns and statutory disclosures.
-
-### Step 5: Citation & Link Integrity Audit
-Run the automated citation verification suite:
-```powershell
-npm run citations
-```
-To run live network probing across all endpoints:
-```powershell
-node scripts/verify_citation_links.js --live
-```
-*Pass Criteria*: 0 syntax errors, 0 unauthorized domains, 0 HTTP failures.
-
-### Step 6: Schema Conformance & Syntax Validation
-Validate structure and conformance against test fixtures:
-```powershell
-npm run validate
-npm run conformance
-```
-*Pass Criteria*: 100% schemas valid, 12/12 conformance fixtures passing, 0 defects.
-
-### Step 7: Cryptographic Merkle Manifest Re-generation
-Recompute per-file SHA-256 hashes and update the root Merkle digest:
-```powershell
-npm run manifest
-npm run manifest:check
-```
-Record the resulting root hash in release notes.
-
-### Step 8: Client Pinning & Trust Anchor Verification
-1. Add the updated root digest to `PINNED_RELEASE_ROOTS` in [`src/index.js`](../src/index.js).
-2. For remote edge synchronization, verify Ed25519 digital signature validation against the MudraForge Root Authority.
-
-### Step 9: Dual Regression Testing
-Execute both package unit tests and the core engine verification suite:
-```powershell
-# 1. Package Regression Suite (88 test suites)
-npm run test
-
-# 2. Engine Unified Test Runner (68 suites)
-npm --prefix ../../mudraforge-sarvam test
-
-# 3. Adesha Benchmark Runner (6 scenarios)
-node ../../mudraforge-sarvam/tests/benchmarks/adesha_benchmark_challenge_01_runner.js
-```
-*Pass Criteria*: 100% passing across all 156 test suites and benchmark scenarios with 0 regressions.
-
-### Step 10: SemVer Release & Distribution
-1. Bump package version in `package.json` and synchronize `STATUTORY_CLIENT_VERSION` in `src/index.js`.
-2. Document all changes in `CHANGELOG.md`.
-3. Publish package to the public registry: `npm publish --access public`.
-4. Deploy / seed edge catalogs on Cloudflare Workers KV.
-5. Verify in a clean downstream consumer project (`scratch/fresh_public_npm_consumer`).
-
----
-
-## 6. Anti-Drift & Security Invariants
-
-All engineers and automated agents contributing to OKF provisions must uphold five mandatory invariants:
-
-| Invariant | Operational Requirement | Verification Mechanism |
-|---|---|---|
-| **Rule 2: Stale Reference Scan** | After renaming or deprecating any provision, scan the entire codebase for stale references. | PowerShell `Get-ChildItem -Recurse \| Select-String` returns zero matches. |
-| **Rule 3: Single Execution Path** | No duplicate inline calculators. All dispatchers delegate to canonical USVM kernel (`@mudraforge/statutory/usvm`). | Unit tests confirm identical mathematical output across all entrypoints. |
-| **Rule 4: Regex User Input Escaping** | User-supplied search queries must be sanitized with `replace(/[.*+?^${}()\|[\]\\]/g, '\\$&')`. | Unit tests verify queries containing `(`, `)`, `[`, `]`, `*`. |
-| **Rule 5: No Dead Schema Parameters** | Every parameter declared in `section.json` must be evaluated by the execution runtime. | Parameter mapping audit in `statutory_commons.js`. |
-| **Rule 11: Statutory Truth Over Engine Output** | Calculations and effective dates must match independent legal ground truth, not merely agent agreement. | Parameterized test suites testing cumulative prior purchases and temporal dates. |
-
----
-
-## 7. Verifiable Release Artifacts & Evidence Ledger
-
-Claims of test passage and release integrity are substantiated by the following reproducible artifacts:
-
-| Verification Layer | Active Release Evidence | Location / Verification Command |
-|---|---|---|
-| **Cryptographic Root** | `sha256-4bbe36c3db841b833dd2bebbd6c1c5ed735498e7b20d1221c323ceb211529fe0` | `npm run manifest:check` across all 86 files |
-| **Citation Network Liveness** | 76/76 passing citations across 5 regulatory domains (0 failures) | `node scripts/verify_citation_links.js --live` |
-| **Statutory Schema Conformance** | 29/29 sections, 30 circulars, 27 forms passing OKF v0.2 linter | `npm run validate` |
-| **Package Regression** | 88/88 test suites passing with 100% reproducible precision | `npm run test` in `packages/statutory` |
-| **Engine Invariant Regression** | 68/68 test suites passing across governance runtime and TLA+ oracles | `npm test` in `mudraforge-sarvam` |
-| **Adesha Benchmark Challenge 01** | 6/6 scenarios scored (Base 100/100, Variants A-E verified) | `node mudraforge-sarvam/tests/benchmarks/adesha_benchmark_challenge_01_runner.js` |
-| **Live NPM Consumer** | Installed and verified live from registry in clean consumer | `node scratch/fresh_public_npm_consumer/test_live_npm_benchmark.js` |
-
----
-
-## 8. Pre-Flight Maintenance Checklist
-
-Before closing any maintenance task or cutting a new release, verify that each item is completed:
-
-- [ ] All 29 statutory provisions contain complete and valid `section.json` contracts.
-- [ ] Every citation URL uses `https://` and resolves to an approved regulatory domain.
-- [ ] `npm run citations` reports 0 defects and 0 unauthorized domains.
-- [ ] `npm run validate` passes with 0 schema errors.
-- [ ] `npm run conformance` passes 12/12 fixture tests.
-- [ ] `npm run manifest:check` verifies all 86 files against SHA-256 digests.
-- [ ] `PINNED_RELEASE_ROOTS` in `src/index.js` includes the active manifest root hash.
-- [ ] Two-pass precision lookup correctly resolves single-digit sections (`8`, `9(3)`).
-- [ ] All 88 package tests and 68 engine regression suites pass with 0 failures.
-- [ ] Stale reference scan returns zero matches for deprecated names or legacy domains.
-- [ ] Version number in `package.json` exactly matches `STATUTORY_CLIENT_VERSION`.

package/docs/PILOT_EVALUATION_GUIDE.md

@@ -1,215 +0,0 @@
-# MudraForge Adesha — Supervised Shadow Pilot Evaluation Guide
-## Benchmarking Autonomous Finance AI Against Historical Accounts Payable Records
-
-> **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. Executive Context & Purpose
-
-This document specifies the protocol for conducting a **Supervised Shadow Pilot** of MudraForge Adesha within an enterprise finance department.
-
-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.
-
-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. 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. Candidate Ingestion Schema & Phased Staging
-
-To minimize operational demands on enterprise accounting personnel, the pilot follows a two-stage progressive protocol:
-
-### 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.
-
-### 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.
-
-### 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, 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. Adesha Shadow Execution Pipeline
-
-The Supervised Shadow Pilot operates entirely offline as a non-intrusive analytical pipeline:
-
-```
-[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: USVM Declarative Grounding   │
-│  (@mudraforge/statutory/usvm)          │
-│  - Declarative AST rule evaluation     │
-│  - Cumulative FY threshold evaluation  │
-│  - 5-stage rational BigInt arithmetic  │
-│  - Statutory withholding derivation    │
-└────────────────────────────────────────┘
-              │
-              ▼
-┌────────────────────────────────────────┐
-│  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 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).
-
-- **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 & Tri-Part Variance Classification
-
-At the conclusion of the evaluation, the enterprise finance leadership receives a comprehensive **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.
-
-### 2. Tri-Part Variance Classification Register
-To provide actionable clarity without premature legal assumptions, all identified variances are categorized into three distinct classes:
-
-- **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.
-
-### 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.
-
-### 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 |
-| :--- | :--- |
-| 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 Protection
-
-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:
-
-### 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.
-
-### 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 Safeguards
-
-To maintain clear enterprise governance, the pilot operates under absolute operational restrictions:
-
-- **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. Quantitative Evaluation & Acceptance Benchmarks
-
-The success of the Supervised Shadow Pilot is measured against objective, pre-agreed quantitative benchmarks:
-
-| Evaluation Benchmark | Objective Definition | Success Threshold |
-| :--- | :--- | :--- |
-| **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 Supervised Shadow Pilot
-
-To schedule an architecture review, receive sample ingestion schemas, or coordinate a Supervised Shadow Pilot for your finance organization:
-
-- **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)
-- **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

@@ -1,33 +0,0 @@
-# Published Release & Provenance Ledger
-
-This document records the cryptographic provenance, normative specifications, and formal assurance artifacts for `@mudraforge/statutory`.
-
----
-
-## Release Baseline Ledger
-
-| Item | Value |
-|---|---|
-| **Package Release** | **`v2.13.0`** (Production Release) |
-| **Knowledge Specification** | **Google Open Knowledge Format (OKF v0.2) + MudraForge Statutory Schema Extension** |
-| **Regulatory Snapshot** | **CBDT / CBIC / MCA / MSME Baseline: November 2026** |
-| **Corpus Quality Card** | 100% Primary Citation Resolution (125/125 URLs verified; 182 citations across 46 provisions) in [`docs/CORPUS_QUALITY.md`](./CORPUS_QUALITY.md) |
-| **Architecture Decision Records** | 7 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) (`sha256-7ffc75e8611a9c966eea756dd544fdae9144e2318d3478633232bb876d05e364` across 191 files) |
-| **Temporal Framework** | Dual-Act Bridge: *Income-tax Act, 1961* & *Income-tax Act, 2025* |
-| **Verification Gate** | 100% Pass across all 166 test suites (cumulative thresholds, legislative sunsets, and excess math) |
-
----
-
-## Cryptographic & Epistemic Scope
-
-The SHA-256 root hash in `okf/manifest.json` provides mathematical verification of **byte-level integrity** (ensuring local files have not been corrupted, altered, or partially written). A hash certifies that bytes match the published release; it does not by itself constitute legal or statutory authority. 
-
-Epistemic authority is established strictly via:
-1. Primary gazette citations and statutory text enacted by Parliament.
-2. Executive circulars and notifications issued by the CBDT, CBIC, MCA, and Ministry of MSME.
-3. Cryptographic Ed25519 signatures anchored to the MudraForge Root Authority.
-4. Independent legal ground-truth test suites parameterizing effective dates and cumulative turnover thresholds.

package/docs/VERIFICATION.md

@@ -1,106 +0,0 @@
-# @mudraforge/statutory: Verification & Conformance Report
-
-> **Audited Package**: `@mudraforge/statutory` v2.13.0 (Public Open Knowledge Commons)  
-> **Target Runtime**: Node.js v20+, Bun, Deno, Cloudflare Workers  
-> **Public Test Status**: 166 Multi-Domain Regression & Verification Suites Passing (100% Reproducible)  
-> **Cryptographic Scope**: SHA-256 Merkle root digest over 191 bundled knowledge files (0 mismatches)  
-
----
-
-## 1. Scope & Epistemic Limitations
-
-In enterprise software and autonomous compliance systems, **a passing test suite is evidence of conformance under tested conditions—it is not an absolute judicial proof that every statutory interpretation or real-world edge case is correct**.
-
-This report documents:
-1. The reproducible public test commands used to verify OKF schemas, circular frontmatter, and temporal state transitions.
-2. The differential tests used to check statutory threshold calculations against published legal sources.
-3. The cryptographic integrity checks certifying that bundled local files match the published release byte-for-byte.
-4. The vendor-neutral conformance fixtures ensuring third-party parsers interpret records consistently.
-
-> **Commercial Architecture Reference**:  
-> For the commercial Adesha Autonomous Finance Runtime's formal verification—including TLC model checking of the payment authorization state space, adversarial mutation testing (MUTANT-01 to MUTANT-12), and Two-Generals banking timeout recovery—see [`ADESHA_ASSURANCE_OVERVIEW.md`](./ADESHA_ASSURANCE_OVERVIEW.md).
-
----
-
-## 2. Reproducing Public Package Checks Locally
-
-Any developer, Chartered Accountant, or auditor can reproduce the verification checks for this open-source package locally with **zero external network access**:
-
-```bash
-# 1. Run the multi-domain regression suite (88 test suites covering all provisions & failure modes)
-npm test
-
-# 2. Run the fail-closed OKF schema & circular frontmatter validator
-npm run validate
-
-# 3. Run the vendor-neutral OKF conformance suite (12 fixture assertions)
-npm run conformance
-
-# 4. Generate the corpus quality card (Google Data Cards Playbook standard)
-npm run quality
-
-# 5. Verify cryptographic SHA-256 Merkle root integrity of all bundled files
-npm run manifest:check
-
-# 6. Recompile the statutory catalog from source files
-npm run catalog
-```
-
----
-
-## 3. Cryptographic Integrity vs. Statutory Legal Truth
-
-It is critical to distinguish **byte-level distribution integrity** from **statutory legal ground truth**:
-
-- **What a SHA-256 hash proves**: Byte fidelity. It proves that the downloaded JSON schema or Markdown circular matches the exact byte sequence recorded in the Merkle manifest at publication time, ensuring no corrupted or partial writes.
-- **What a SHA-256 hash does NOT prove**: Statutory correctness. A cryptographically intact file can still contain a legally outdated or misconstrued provision.
-- **How legal truth is verified**: Every provision must pass our differential test suite (`test.js`) and corpus quality audit (`scripts/corpus_quality_report.js`), verifying calculations against primary Union Gazettes, official CBDT/CBIC circulars, and independent CA legal baselines.
-
----
-
-## 4. Differential Test Coverage for Statutory Outcomes
-
-The regression suite (`test.js`) verifies calculations against independently formulated legal baselines across key statutory boundary conditions:
-
-| Provision / Domain | Tested Condition | Legal Ground Truth | Test Outcome |
-| :--- | :--- | :--- | :--- |
-| **Direct Tax: Section 194Q** | Cumulative purchases cross ₹50L threshold | Deduct 0.1% strictly on excess over ₹50L, NOT on gross | [PASS] Verified |
-| **Direct Tax: Section 194Q** | Inoperative or missing vendor PAN | Section 206AA rate capped strictly at 5.0% | [PASS] Verified |
-| **Direct Tax: Section 194J** | Technical Services vs. Professional Fees | 2% rate for FTS, 10% rate for professional services | [PASS] Verified |
-| **Direct Tax: Section 206C(1H)** | Evaluated on or after 1 April 2025 | Finance Act 2025 sunsets section w.e.f. 01-04-2025 | [PASS] Intercepted |
-| **Indirect Tax: CGST Sec 17(5)** | Blocked ITC negative list categories | Motor vehicles <= 13 seats, food/catering, club memberships | [PASS] Blocked |
-| **MSME: MSMED Sections 15 & 16** | Payment window & compound penal interest | 15 days default / 45 days written contract; 3x RBI bank rate | [PASS] Verified |
-| **Cross-Border: IRC §§ 901/904** | Foreign Tax Credit limitation baskets | Pass-through entity taxes, IRS Schedule K-3 requirement | [PASS] Verified |
-| **Corporate M&A: Section 50B** | Slump sale net worth computation & FMV | WDV for depreciable assets, revaluations ignored, 0% GST going concern | [PASS] Verified |
-| **Local Resilience (Dead Network)**| Edge query unreachable / simulated dead network | Gracefully falls back to local OKF disk snapshot | [PASS] Verified |
-| **Explicit Retrieval Modes** | `mode: 'local'` requested by caller | Fails closed if provision unbundled; 0 network calls | [PASS] Verified |
-
----
-
-## 5. Vendor-Neutral OKF Conformance Assertions
-
-The conformance runner (`conformance/test_conformance.js`) tests parser behavior against standalone JSON and Markdown fixtures in `conformance/fixtures/`:
-
-1. **Schema Ingestion**: Minimal valid schemas (`valid_minimal_section.json`) and full metadata schemas (`valid_full_section.json`) accepted.
-2. **Temporal Bound Sanity**: Rejects schemas with missing effective dates (`invalid_missing_effective_period.json`) or inverted timelines (`invalid_malformed_temporal_dates.json`).
-3. **Mandatory Identity**: Rejects schemas missing `sectionCode` (`invalid_missing_section_code.json`).
-4. **Google OKF Frontmatter Extraction**: Correctly extracts YAML frontmatter from administrative circulars (`valid_circular_frontmatter.md`).
-
----
-
-## 6. Reproducible Release Tarball Verification
-
-Every published release tarball can be independently verified against Git tag `v2.13.0`:
-
-```bash
-# 1. Pack the distribution tarball
-npm pack
-
-# 2. Compute the SHA-256 checksum of the tarball (PowerShell)
-Get-FileHash mudraforge-statutory-2.13.0.tgz -Algorithm SHA256
-
-# Or in Linux / macOS:
-# sha256sum mudraforge-statutory-2.13.0.tgz
-```
-
-The resulting package contains exactly 124 audited files (zero extraneous build artifacts, zero internal development scripts).