# NEPHIS Unified Billing, Credits & Consumption Architecture

This document outlines the official commercial pricing, consumption units, credit mechanics, and FinOps policies powering the **NEPHIS Sovereign Compute Substrate** across all three execution engines: **Eschaton**, **Thanaton**, and **Mnemon-DB**.

---

## 🏛️ Executive Summary & Core Philosophy

NEPHIS replaces fragmented billing models (per-second container runtimes, cold-boot penalties, and idle cloud database charges) with an **Atomic Unified Credit System**.

Every operation executed across the fabric maps directly to verifiable units of work:

```
+--------------------------------------------------------------------------------------------------+
|                                  NEPHIS UNIFIED CREDIT ARCHITECTURE                              |
+------------------------------------+-----------------------------+-------------------------------+
|     ZERO-HUMAN SIGNUP TRIAL        |     CLAIMED DEVELOPER TIER  |     PRODUCTION & SCALE TIER   |
|  • 500 Credits Instant Allocation  |  • 2,000 Monthly Credits    |  • 50,000+ Monthly Credits    |
|  • Solved via Proof-of-Work (PoW)  |  • Device-to-Cloud Link     |  • Dedicated MicroVM Pools    |
|  • Laptop API Key Active Instantly |  • Zero Key Invalidation    |  • BYOC & Custom Schedulers   |
+------------------------------------+-----------------------------+-------------------------------+
```

---

## 💎 The Common Currency Anchor

Every single credit across all three sovereign engines is anchored to the exact same physical hardware foundation:

$$\mathbf{1\text{ Credit}} = \mathbf{\$0.00020\text{ USD}} \quad \Longleftrightarrow \quad \mathbf{5,000\text{ Credits}} = \mathbf{\$1.00\text{ USD}}$$

### Hardware Equivalence Unit (Normalized SCU):
- **CPU:** ~1.0 second of dedicated 100% vCPU execution (or 100ms on a 2-vCPU burst).
- **RAM:** 1 minute of 128MB reserved memory.
- **Database:** 1,000 standard indexed B-tree queries.
- **MicroVM:** 1 minute of active light compute (or 60 seconds of scale-to-zero stasis @ $0.00).

---

## ⚡ Master Unified Credit Balance Matrix

| Subsystem | Operation | Platform Hardware Cost | Credit Fee | USD Equivalent | Gross Margin | Anti-Arbitrage Guardrail |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **ESCHATON (Compiler)** | Interpreted Run (Python/JS/TS/Ruby/PHP/Bash) | 0.02s vCPU (~$0.00001) | **1 Credit** | \$0.00020 | **95.0%** | Max 5s wall-clock timeout |
| **ESCHATON (Compiler)** | Compiled Binary (Go/C/C++/C#/Java) | 0.45s vCPU (~$0.00004) | **2 Credits** | \$0.00040 | **90.0%** | Incremental cache reuse |
| **ESCHATON (Compiler)** | Heavy Compilation (Rust/GCC/Haskell/Swift) | 1.80s vCPU (~$0.00012) | **4 Credits** | \$0.00080 | **85.0%** | Capped at 15s build limit |
| **ESCHATON (Compiler)** | Memory Profiler (Valgrind/ASan/TSan) | 4.50s vCPU (~$0.00030) | **15 Credits** | \$0.00300 | **90.0%** | Max 1 concurrent job |
| **MNEMON (Database)** | Standard Indexed Queries (1,000 queries) | 1,000 queries (~$0.00003)| **1 Credit** | \$0.00020 | **85.0%** | Requires B-Tree / GIN index |
| **MNEMON (Database)** | Unindexed Slow Query Scan (>100ms CPU) | >100ms CPU scan (~$0.00008)| **2 Credits/s** | \$0.00040/s | **80.0%** | Circuit breaker auto-kills @ 10s |
| **MNEMON (Database)** | CoW Reflink Branch Creation | Metadata fork (~$0.00002)| **1 Credit** | \$0.00020 | **90.0%** | 0MB initial disk clone |
| **MNEMON (Database)** | Vector HNSW (1,536-dim, 200 queries) | 200 queries (~$0.00012) | **5 Credits** | \$0.00100 | **88.0%** | SIMD AVX-512 accelerated |
| **MNEMON (Database)** | Scale-to-Zero Stasis | 0% CPU, 0 MB disk write | **0 Credits** | **\$0.00000** | **100.0%** | Auto-freezes after timeout via cgroup.freeze |
| **THANATON (MicroVM)** | Cold Boot / Wake Hydration | KVM page-in (~$0.00006) | **5 Credits** | \$0.00100 | **94.0%** | Sub-6.14ms SLA |
| **THANATON (MicroVM)** | Active Run (128MB RAM) | 1 minute vCPU (~$0.00002) | **1 Credit/min**| \$0.00020/min | **90.0%** | Auto-sleeps on idle |
| **THANATON (MicroVM)** | Active Run (512MB RAM) | 1 minute vCPU (~$0.00004) | **2 Credits/min**| \$0.00040/min | **90.0%** | Auto-sleeps on idle |
| **THANATON (MicroVM)** | Scale-to-Zero Stasis | 0.0% CPU, compressed RAM | **0 Credits** | **\$0.00000** | **100.0%** | Process frozen in stasis |
| **THANATON (MicroVM)** | Full Project Deployment Build | SquashFS build (~$0.00050)| **25 Credits** | \$0.00500 | **90.0%** | Max 32MB archive size |

---

## 🛡️ Autonomous FinOps & Safety Guarantees

### 1. Zero Human Signup ("Proof-of-Work Bootstrap")
- AI agents running autonomously in IDEs (Cursor, Claude Desktop, Windsurf) or CI/CD pipelines can issue `npx -y nephis-mcp` or `POST /v1/auth/claim-agent-key`.
- The client solves a lightweight Proof-of-Work (Hashcash, difficulty 4) to prevent bot spam without requiring interactive CAPTCHAs, credit cards, or phone numbers.
- Instantly issues an active API key (`mrd_live_...` or `esk_live_...`) with **500 trial credits**.

### 2. Device-to-Cloud Claim Flow (`/claim?key=mrd_live_...`)
- Developers can claim ownership of their agent's tenant at `https://nephis.theeducode.com/claim?key=...`.
- Linking a GitHub account executes `POST /v1/auth/claim-tenant`.
- Upgrades the tenant credit pool to **2,000 monthly credits**.
- **Zero Key Invalidation Guarantee:** The active API key on the developer's laptop remains untouched and valid—no environment variables need to be regenerated or updated.

### 3. Automatic Platform Error Refunds
- If any upstream engine (Eschaton Brain, Thanaton Daemon, Mnemon Postgres) returns a **5xx server error**, the gateway immediately issues an automatic credit refund.
- Net negative deltas decrement the daily usage and restore the tenant balance in hot memory and on disk.

### 4. True Scale-to-Zero ($0.00 Idle Cost)
- Dormant PostgreSQL tenants and sleeping Thanaton MicroVMs are automatically frozen into stasis (0.0% CPU, 0 IOPS).
- Wakeup occurs in <200µs on incoming TCP packets or API calls.
- Inactive branches and sleeping sandboxes consume **0 ongoing credits**.

---

## 🔄 Dual-Tier Persistence Architecture

```mermaid
flowchart LR
    REQ["Incoming API Request"] --> GW["Nephis Gateway (:8080)"]
    GW --> MEM["Hot Atomic RAM<br/>(Checked in <1µs)"]
    MEM -- "Insufficient Balance (< Cost)" --> REJ["HTTP 402 Payment Required"]
    MEM -- "Sufficient Balance" --> EXE["Execute Engine Call<br/>(Eschaton / Thanaton / Mnemon)"]
    EXE --> STATUS{"Status Code?"}
    STATUS -- "2xx / 4xx" --> NET["Net Delta Buffered in Gateway"]
    STATUS -- "5xx" --> REF["Immediate Credit Refund"]
    NET --> FLUSH["Background Flusher<br/>(Pushes every 5s to Supabase)"]
    FLUSH --> SUPA[("Supabase PostgreSQL<br/>public.tenants & api_keys")]
```

1. **Hot Atomic RAM (<1µs):** Every API key request checks and decrements the balance in RAM using atomic CAS (`sync/atomic`) instructions. Zero disk I/O occurs on critical request paths.
2. **Net Delta Flusher (Every 5s):** The gateway buffers deductions and refunds into a thread-safe delta map. A background goroutine executes `public.deduct_tenant_credits()` against Supabase, ensuring persistent audit trails without degrading sub-millisecond API latency.

---

## 📦 Commercial Plan Matrix

| Plan Tier | Monthly Price | Monthly Credits Included | Concurrency Workers | Support & SLA |
| :--- | :--- | :--- | :--- | :--- |
| **Developer Trial** | **$0** (PoW Bootstrap) | **500 Credits** | 5 Parallel Workers | Community GitHub Discussions |
| **Claimed Developer** | **$0** (GitHub Login) | **2,000 Credits / mo** | 20 Parallel Workers | Community & Discord Support |
| **Team Pro** | **$49 / mo** | **25,000 Credits / mo** | 50 Parallel Workers | Priority Support (<4h SLA) |
| **Enterprise Sovereign** | **$199 / mo** | **120,000 Credits / mo** | Unlimited (Full Node Saturation) | Dedicated VPC / BYOC & Slack Channel |
