@mudraforge/statutory 2.12.1 → 2.14.0

package/examples/README.md

@@ -1,56 +0,0 @@
-# MudraForge Statutory & Adesha: End-to-End Execution Traces
-
-> **Purpose**: Demonstrates the concrete operational bridge connecting public OKF statutory rules with the commercial Adesha Autonomous Finance Runtime.  
-> **Demonstration Notice**: This trace contains synthetic transaction data and modeled authorization, banking, and ledger events. It does not connect to a real bank, verify a live biometric event, or execute a real-world payment. All PANs, GSTINs, and account numbers are explicitly synthetic test fixtures.
-
----
-
-## 1. Overview
-
-A common question from developers and Chief Financial Officers is:
-> *"How does a declarative statutory tax rule in `@mudraforge/statutory` translate into a safe, real-world corporate payment without giving an AI agent uncontrolled access to company bank accounts?"*
-
-This directory contains concrete, audited end-to-end execution traces illustrating every stage of that journey:
-
-```
-[Raw Vendor Invoice]
-        ↓
-Stage 1: Ingestion & Vendor PAN/GSTIN Validation
-        ↓
-Stage 2: OKF Rule Resolution (Section 194Q TDS on Purchase of Goods)
-        ↓
-Stage 3: Deterministic Tax Calculation (0.1% on excess over ₹50L, GST unbundled per CBDT 13/2021)
-        ↓
-Stage 4: Adesha Payment Authorization Lease (Single-use cryptographic token, amount-locked)
-        ↓
-Stage 5: Human-In-The-Loop Mobile Authorization (CFO Biometric/Passkey Approval on Mobile)
-        ↓
-Stage 6: Host-to-Host Corporate Bank Rail Disbursement (RTGS Settlement with Bank UTR)
-        ↓
-Stage 7: General Ledger Writeback (ERP Balanced Double-Entry Journal Entry: Debits ≡ Credits)
-```
-
----
-
-## 2. Artifacts in this Directory
-
-| File | Description |
-| :--- | :--- |
-| [`invoice_deduction_trace.json`](./invoice_deduction_trace.json) | Full machine-readable execution trace payload covering all 7 stages. |
-| [`simulate_end_to_end_trace.js`](./simulate_end_to_end_trace.js) | Standalone simulation runner printing the step-by-step audit lifecycle. |
-
----
-
-## 3. Running the Trace Locally
-
-Any developer can run this simulation locally with zero external network access:
-
-```bash
-node examples/simulate_end_to_end_trace.js
-```
-
-Or via npm:
-
-```bash
-npm run example:trace
-```

package/examples/invoice_deduction_trace.json

@@ -1,149 +0,0 @@
-{
-  "$schema": "https://mudraforge.in/schemas/v1/execution-trace.json",
-  "traceId": "trace_e2e_2026_sec194q_001",
-  "timestamp": "2026-04-15T10:30:00Z",
-  "isSyntheticDemonstrationFixture": true,
-  "disclaimer": "Demonstration only: This trace contains synthetic transaction data and simulated authorization, banking and general ledger events. It does not connect to a real bank, verify a real biometric event, or execute a live payment.",
-  "workflow": "ACCOUNTS_PAYABLE_STATUTORY_DISBURSEMENT",
-  
-  "stage1_incoming_invoice": {
-    "invoiceNumber": "INV-2026-891",
-    "invoiceDate": "2026-04-15",
-    "vendor": {
-      "legalName": "Apex Synthetic Industrial Steels Private Limited (Demonstration Fixture)",
-      "pan": "AAAPA0000A",
-      "panStatus": "OPERATIVE_VERIFIED_SYNTHETIC",
-      "gstin": "27AAAPA0000A1Z5",
-      "msmeStatus": "NOT_APPLICABLE_LARGE_ENTERPRISE"
-    },
-    "currency": "INR",
-    "lineItems": [
-      {
-        "description": "Hot Rolled Steel Coils (Grade IS 2062)",
-        "quantity": 120,
-        "unit": "MT",
-        "basicAmountInr": 6000000.00
-      }
-    ],
-    "basicGoodsAmountInr": 6000000.00,
-    "gstRatePercent": 18.0,
-    "cgstAmountInr": 540000.00,
-    "sgstAmountInr": 540000.00,
-    "totalGstAmountInr": 1080000.00,
-    "grossInvoiceAmountInr": 7080000.00
-  },
-
-  "stage2_okf_statutory_rule_resolution": {
-    "provisionResolved": "194Q",
-    "source": "LOCAL_OKF_FS",
-    "governingStatute": "Income-tax Act, 1961 (Act No. 43 of 1961)",
-    "successorStatute": "Income-tax Act, 2025 Section 393(1) Table 8 Item (ii)",
-    "temporalStatus": "ACTIVE",
-    "retrievalMode": "LOCAL_OFFLINE_FASTPATH",
-    "statutoryRule": {
-      "thresholdInr": 5000000.00,
-      "buyerPriorYearTurnoverCr": 10.00,
-      "standardDeductionRatePercent": 0.1,
-      "inoperativePanPenaltyRatePercent": 5.0,
-      "taxableBaseScope": "EXCESS_OVER_50_LAKHS_ONLY",
-      "gstUnbundlingMandated": true,
-      "citation": "CBDT Circular No. 13 of 2021 (Dated 30 June 2021)"
-    }
-  },
-
-  "stage3_deterministic_statutory_computation": {
-    "engine": "MudraForge Deterministic Statutory Calculator",
-    "inputs": {
-      "buyerPriorYearGrossTurnoverCr": 24.50,
-      "isBuyerEligible": true,
-      "priorPurchasesInCurrentFYInr": 4500000.00,
-      "currentInvoiceBasicInr": 6000000.00,
-      "cumulativeFYPurchasesInr": 10500000.00
-    },
-    "calculationSteps": {
-      "statutoryThresholdInr": 5000000.00,
-      "portionExemptFromPriorBalanceInr": 500000.00,
-      "taxableBaseForThisInvoiceInr": 5500000.00,
-      "gstComponentExcludedInr": 1080000.00,
-      "tdsRateAppliedPercent": 0.1,
-      "tdsDeductionCalculatedInr": 5500.00,
-      "netPayableToVendorInr": 7074500.00
-    },
-    "verificationStatus": "DETERMINISTIC_PASS"
-  },
-
-  "stage4_adesha_payment_authorization_lease": {
-    "runtime": "MudraForge Adesha Sovereign Runtime",
-    "leaseId": "lease_2026_04_apex_89a1",
-    "leaseStatus": "PENDING_HUMAN_AUTHORIZATION",
-    "singleUseLeaseToken": "sha256-4f9e8a71b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9",
-    "authorizedRecipient": {
-      "beneficiaryName": "Apex Synthetic Industrial Steels Pvt Ltd (Demonstration Fixture)",
-      "bankAccountNumber": "0000000000009812",
-      "ifscCode": "TEST0000001"
-    },
-    "maximumAuthorizedDisbursementInr": 7074500.00,
-    "leaseExpiresAt": "2026-04-15T12:00:00Z",
-    "formalState": "LEASE_ISSUED_UNCONSUMED"
-  },
-
-  "stage5_human_in_the_loop_authorization": {
-    "channel": "Adesha Mobile Authority Harness (Simulated Android/iOS)",
-    "decision": "APPROVED",
-    "authorizedBy": {
-      "officerId": "usr_cfo_synthetic_01",
-      "email": "cfo@example-enterprise.invalid",
-      "role": "CHIEF_FINANCIAL_OFFICER"
-    },
-    "authenticationFactor": "SIMULATED_BIOMETRIC_PASSKEY_VERIFIED",
-    "authorizedAt": "2026-04-15T10:32:15Z",
-    "stateTransition": "LEASE_ISSUED_UNCONSUMED -> AUTHORIZED_FOR_SETTLEMENT"
-  },
-
-  "stage6_banking_rail_disbursement": {
-    "bankingPartner": "Simulated Corporate Banking Gateway (H2H RTGS)",
-    "rail": "RTGS_SIMULATED",
-    "transportIdempotencyKey": "idem_synthetic_inv891_20260415_01",
-    "bankUniqueTransactionReference": "SIMULATED-RTGS-UTR-2026-891",
-    "disbursedAmountInr": 7074500.00,
-    "settlementTimestamp": "2026-04-15T10:32:18Z",
-    "networkOutcome": "SIMULATED_HTTP_200_SETTLED_CONFIRMED"
-  },
-
-  "stage7_general_ledger_double_entry_writeback": {
-    "erpSystem": "Enterprise ERP (SAP S/4HANA / Zoho Books / Tally Prime)",
-    "voucherNumber": "JV-2026-04-0042",
-    "postingDate": "2026-04-15",
-    "journalLines": [
-      {
-        "account": "Purchases / Cost of Goods Sold (IS 2062)",
-        "type": "DEBIT",
-        "amountInr": 6000000.00
-      },
-      {
-        "account": "Input CGST Receivable (9%)",
-        "type": "DEBIT",
-        "amountInr": 540000.00
-      },
-      {
-        "account": "Input SGST Receivable (9%)",
-        "type": "DEBIT",
-        "amountInr": 540000.00
-      },
-      {
-        "account": "TDS Payable under Section 194Q",
-        "type": "CREDIT",
-        "amountInr": 5500.00
-      },
-      {
-        "account": "HDFC Corporate Bank Operating Account",
-        "type": "CREDIT",
-        "amountInr": 7074500.00
-      }
-    ],
-    "totalDebitsInr": 7080000.00,
-    "totalCreditsInr": 7080000.00,
-    "netDiscrepancyInr": 0.00,
-    "equilibriumVerification": "PAISA_LEVEL_PERFECT_BALANCE"
-  }
-}

package/examples/simulate_end_to_end_trace.js

@@ -1,106 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * ═══════════════════════════════════════════════════════════════════════════
- * @mudraforge/statutory — End-to-End Execution Trace Simulator
- * Demonstrates the Complete Bridge from OKF Tax Rules to Adesha Governance
- * ═══════════════════════════════════════════════════════════════════════════
- * Usage:
- *   node examples/simulate_end_to_end_trace.js
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { lookupLocalStatute } from '../src/index.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const TRACE_PATH = path.join(__dirname, 'invoice_deduction_trace.json');
-
-export function runTraceSimulation() {
-    console.log('===========================================================================');
-    console.log('MUDRAFORGE & ADESHA: END-TO-END AP STATUTORY EXECUTION TRACE');
-    console.log('===========================================================================');
-    console.log('[NOTE] DEMONSTRATION FIXTURE ONLY:');
-    console.log('This trace models synthetic transaction data and simulated authorization,');
-    console.log('banking, and general ledger events to illustrate the Adesha governance contract.');
-    console.log('It does not connect to a real bank, verify a live biometric event, or execute a real payment.');
-    console.log('===========================================================================\n');
-
-    const trace = JSON.parse(fs.readFileSync(TRACE_PATH, 'utf8'));
-
-    // Stage 1: Incoming Invoice
-    console.log('── STAGE 1: INCOMING VENDOR INVOICE INGESTION ──');
-    const inv = trace.stage1_incoming_invoice;
-    console.log(`Invoice No:     ${inv.invoiceNumber} (Dated: ${inv.invoiceDate})`);
-    console.log(`Vendor:         ${inv.vendor.legalName} (PAN: ${inv.vendor.pan})`);
-    console.log(`Basic Value:    INR ${inv.basicGoodsAmountInr.toLocaleString('en-IN')}`);
-    console.log(`GST (18%):      INR ${inv.totalGstAmountInr.toLocaleString('en-IN')}`);
-    console.log(`Gross Total:    INR ${inv.grossInvoiceAmountInr.toLocaleString('en-IN')}\n`);
-
-    // Stage 2: OKF Rule Resolution
-    console.log('── STAGE 2: OPEN KNOWLEDGE FORMAT (OKF) RULE RESOLUTION ──');
-    const statute = lookupLocalStatute('194Q');
-    console.log(`Provision:      ${statute.statutorySection} (${statute.governingStatute})`);
-    console.log(`Successor:      ${statute.successorStatute} (${statute.successorSection})`);
-    console.log(`Threshold:      INR ${statute.keyStatutoryThresholds.annualPurchaseThresholdInr.toLocaleString('en-IN')}`);
-    console.log(`Standard Rate:  ${statute.keyStatutoryThresholds.standardDeductionRatePercent}%`);
-    console.log(`Taxable Scope:  ${statute.keyStatutoryThresholds.taxableBaseScope}\n`);
-
-    // Stage 3: Deterministic Statutory Computation
-    console.log('── STAGE 3: DETERMINISTIC STATUTORY COMPUTATION ──');
-    const calc = trace.stage3_deterministic_statutory_computation;
-    console.log(`Prior FY Purchases:     INR ${calc.inputs.priorPurchasesInCurrentFYInr.toLocaleString('en-IN')}`);
-    console.log(`Cumulative Total:       INR ${calc.inputs.cumulativeFYPurchasesInr.toLocaleString('en-IN')}`);
-    console.log(`Taxable Base (Excess):  INR ${calc.calculationSteps.taxableBaseForThisInvoiceInr.toLocaleString('en-IN')}`);
-    console.log(`GST Excluded from Base: INR ${calc.calculationSteps.gstComponentExcludedInr.toLocaleString('en-IN')} (CBDT Circular 13/2021)`);
-    console.log(`TDS Deducted (0.1%):    INR ${calc.calculationSteps.tdsDeductionCalculatedInr.toLocaleString('en-IN')}`);
-    console.log(`Net Payable to Vendor:  INR ${calc.calculationSteps.netPayableToVendorInr.toLocaleString('en-IN')}\n`);
-
-    // Stage 4: Adesha Payment Authorization Lease
-    console.log('── STAGE 4: ADESHA CRYPTOGRAPHIC PAYMENT AUTHORIZATION LEASE ──');
-    const lease = trace.stage4_adesha_payment_authorization_lease;
-    console.log(`Lease ID:        ${lease.leaseId}`);
-    console.log(`Single-Use Token: ${lease.singleUseLeaseToken}`);
-    console.log(`Max Authorized:  INR ${lease.maximumAuthorizedDisbursementInr.toLocaleString('en-IN')}`);
-    console.log(`Lease State:     ${lease.formalState}\n`);
-
-    // Stage 5: Human-In-The-Loop Approval
-    console.log('── STAGE 5: HUMAN-IN-THE-LOOP MOBILE HARNESS AUTHORIZATION ──');
-    const hitl = trace.stage5_human_in_the_loop_authorization;
-    console.log(`Channel:         ${hitl.channel}`);
-    console.log(`Decision:        ${hitl.decision}`);
-    console.log(`Authorized By:   ${hitl.authorizedBy.role} (${hitl.authorizedBy.email})`);
-    console.log(`Auth Factor:     ${hitl.authenticationFactor}`);
-    console.log(`State Transition: ${hitl.stateTransition}\n`);
-
-    // Stage 6: Banking Settlement
-    console.log('── STAGE 6: BANK RAIL DISBURSEMENT (HOST-TO-HOST RTGS) ──');
-    const bank = trace.stage6_banking_rail_disbursement;
-    console.log(`Bank Partner:    ${bank.bankingPartner}`);
-    console.log(`Payment Rail:    ${bank.rail}`);
-    console.log(`Bank UTR:        ${bank.bankUniqueTransactionReference}`);
-    console.log(`Outcome:         ${bank.networkOutcome} (${bank.disbursedAmountInr.toLocaleString('en-IN')} INR)\n`);
-
-    // Stage 7: General Ledger Writeback
-    console.log('── STAGE 7: GENERAL LEDGER BALANCED DOUBLE-ENTRY WRITEBACK ──');
-    const gl = trace.stage7_general_ledger_double_entry_writeback;
-    console.log(`Voucher No:      ${gl.voucherNumber} (${gl.erpSystem})`);
-    for (const line of gl.journalLines) {
-        const amtStr = `INR ${line.amountInr.toLocaleString('en-IN', { minimumFractionDigits: 2 })}`;
-        console.log(`  [${line.type.padEnd(6)}] ${line.account.padEnd(42)} ${amtStr.padStart(16)}`);
-    }
-    console.log(`  -------------------------------------------------------------------`);
-    console.log(`  Total Debits:  INR ${gl.totalDebitsInr.toLocaleString('en-IN', { minimumFractionDigits: 2 })}`);
-    console.log(`  Total Credits: INR ${gl.totalCreditsInr.toLocaleString('en-IN', { minimumFractionDigits: 2 })}`);
-    console.log(`  Equilibrium:   ${gl.equilibriumVerification} (Discrepancy: INR ${gl.netDiscrepancyInr.toFixed(2)})\n`);
-
-    console.log('===========================================================================');
-    console.log('[PASS] END-TO-END EXECUTION TRACE VERIFIED WITH ZERO DEFECTS.');
-    console.log('===========================================================================\n');
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-    runTraceSimulation();
-}