Merge pull request #10 from rodrigooler/q2-devnet

Q2 devnet

Author: rodrigooler

.dockerignore

@@ -0,0 +1,9 @@
+.git
+.gitignore
+**/.DS_Store
+**/target
+**/.pytest_cache
+**/.mypy_cache
+**/.venv
+**/node_modules
+**/.next

.gitattributes

@@ -0,0 +1,2 @@
+# Keep generated deploy artifacts out of language stats noise when present.
+target/** linguist-generated

.github/workflows/python-tests.yml

@@ -10,26 +10,31 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
       - name: Set up Python
-        id: setup-python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
         with:
           python-version: '3.11'
+          cache: 'pip'
+          cache-dependency-path: |
+            poc/requirements-dev.txt
+            poc/requirements.txt
 
-      - name: Cache pip downloads
-        uses: actions/cache@v4
+      - name: Restore Python venv cache
+        id: cache-python-venv
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-pip-${{ hashFiles('poc/requirements.txt', 'poc/requirements-dev.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-pip-
+          path: .venv
+          key: ${{ runner.os }}-py311-venv-${{ hashFiles('poc/requirements-dev.txt', 'poc/requirements.txt') }}
 
       - name: Install dependencies
+        if: steps.cache-python-venv.outputs.cache-hit != 'true'
         run: |
+          python -m venv .venv
+          . .venv/bin/activate
           python -m pip install --upgrade pip
           pip install --prefer-binary -r poc/requirements-dev.txt
 
       - name: Run test suite
-        run: pytest poc/tests/ -v
+        run: .venv/bin/pytest poc/tests/ -v

.github/workflows/q2-validate.yml

@@ -0,0 +1,88 @@
+name: Q2 Validate
+
+on:
+  push:
+    branches: [main, q2-devnet]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+          cache: "pip"
+          cache-dependency-path: |
+            poc/requirements-dev.txt
+            poc/requirements.txt
+
+      - name: Restore Python venv cache
+        id: cache-python-venv
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
+        with:
+          path: .venv
+          key: ${{ runner.os }}-py311-venv-${{ hashFiles('poc/requirements-dev.txt', 'poc/requirements.txt') }}
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9
+        with:
+          toolchain: stable
+
+      - name: Restore Rust cache
+        uses: Swatinem/rust-cache@ad397744b0d591a723ab90405b7247fac0e6b8db
+        with:
+          workspaces: |
+            runtime/cognitive -> runtime/cognitive/target
+            programs/raxion-poiq -> programs/raxion-poiq/target
+            proofs -> proofs/target
+            sdk/agent -> sdk/agent/target
+
+      - name: Install Python deps
+        if: steps.cache-python-venv.outputs.cache-hit != 'true'
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install --upgrade pip
+          pip install --prefer-binary -r poc/requirements-dev.txt
+
+      - name: Python tests
+        run: |
+          .venv/bin/pytest poc/tests/ -q
+
+      - name: Runtime cognitive tests
+        run: |
+          cargo test --manifest-path runtime/cognitive/Cargo.toml
+
+      - name: PoIQ program tests
+        run: |
+          cargo test --manifest-path programs/raxion-poiq/Cargo.toml
+
+      - name: RISC0 types tests
+        run: |
+          cargo test -p risc0-types --manifest-path proofs/Cargo.toml
+
+      - name: Coherence cross-validation
+        run: |
+          .venv/bin/python scripts/cross_validate_coherence.py
+
+      - name: SDK examples
+        run: |
+          cargo build --manifest-path sdk/agent/Cargo.toml --example math_agent --example code_agent --example text_agent
+
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: apps/explorer/package-lock.json
+
+      - name: Explorer build
+        run: |
+          cd apps/explorer
+          npm ci --prefer-offline --no-audit --fund=false
+          npm run build

.gitignore

@@ -4,24 +4,51 @@ __pycache__/
 .env
 venv/
 .venv/
+.venv*/
+.python-version
+.uv-cache/
 *.egg-info/
 dist/
 .pytest_cache/
 
 # Rust
 target/
+.cargo-home/
+.cargo-target/
+runtime/agave/
+**/Cargo.lock
 
 # Data
 poc/data/*.jsonl
 poc/data/*.parquet
 poc/benchmarks/results/
+!poc/benchmarks/results/
+poc/benchmarks/results/*
+!poc/benchmarks/results/mmlu_100_q2_baseline.json
 
 # IDE
 .idea/
 .vscode/
 *.swp
+node_modules/
+apps/explorer/.next/
+apps/explorer/out/
+**/package-lock.json
+!apps/explorer/package-lock.json
 
 # OS
 .DS_Store
 Thumbs.db
 Desktop.ini
+
+# Secrets / Wallets
+*.pem
+*.key
+*.seed
+*.mnemonic
+**/.env.local
+**/.env.*.local
+**/id.json
+**/*-keypair.json
+**/wallet*.json
+**/keypair*.json

AGENTS.md

@@ -18,7 +18,16 @@ The core innovation is **Cognitive Finality**: zk-ML proofs that make a collecti
 
 ```
 raxion/
-├── runtime/                    # Neural SVM — fork of Agave (Solana runtime)
+├── apps/
+│   ├── explorer/               # Devnet explorer (Next.js)
+│   └── site/                   # Static website
+│
+├── ops/
+│   ├── docker/                 # Pinned container images/toolchains
+│   └── config/
+│       └── deploy/             # Deployment env templates
+│
+├── runtime/                    # Neural SVM extensions (Agave base fetched on demand)
 │   ├── cognitive/
 │   │   ├── account_types.rs    # CognitiveAccount, NativeMemoryAccount structs
 │   │   ├── scheduler.rs        # CognitiveScheduler — parallel thread dispatch
@@ -97,7 +106,7 @@ A result has Cognitive Finality when:
 VERIFY(π_exec × 3) = ACCEPT
 ∧ VERIFY(π_quality) = ACCEPT
 ∧ CoherenceScore ≥ 0.60
-∧ commit(output, π_poiq, slot) ∈ Solana_L1
+∧ commit(output, π_poiq, slot) ∈ Solana settlement layer
 ```
 
 This is the only valid definition. Do not treat any intermediate state as final.
@@ -114,12 +123,12 @@ This is the only valid definition. Do not treat any intermediate state as final.
 
 | Phase | Status | In Scope |
 |---|---|---|
-| **Phase 0 — Genesis** (Q1 2026) | 🟡 Active | Whitepaper, Python PoC, RISC Zero basic integration |
-| **Phase 1 — Devnet** (Q2–Q3 2026) | 🔜 Next | Agave fork, PoIQ v0.1, Agent SDK v0.1 |
+| **Phase 0 — Genesis** (Q1 2026) | ✅ Completed | Whitepaper, Python PoC, RISC Zero basic integration |
+| **Phase 1 — Devnet** (Q2–Q3 2026) | 🟡 Active | Agave integration, PoIQ v0.1, Agent SDK v0.1 |
 | **Phase 2 — Testnet** (Q4 2026) | 🔜 Planned | GPU proofs, all PoIQ layers, RaxLang v0.1 |
 | **Phase 3 — Mainnet v1** (2027) | 🔜 Planned | ZK ASICs, full protocol, $RAX live |
 
-**Current phase is Phase 0.** Do not implement Mainnet features during Phase 0. The PoC does not need ZK proofs — it needs to validate convergence.
+**Current phase is Phase 1 (Devnet).** Do not implement Testnet/Mainnet-only features in this stage.
 
 ---
 

Anchor.toml

@@ -0,0 +1,18 @@
+[toolchain]
+
+[features]
+resolution = true
+skip-lint = false
+
+[programs.devnet]
+raxion_poiq = "5JVFMV1DvhQD6Tm2BtPBs8zkvGArzRGUYF6GSNw2XUeT"
+
+[registry]
+url = "https://api.apr.dev"
+
+[provider]
+cluster = "Devnet"
+wallet = "~/.config/solana/id.json"
+
+[scripts]
+test = "anchor test"

CLAUDE.md

@@ -6,7 +6,7 @@
 
 ## Project Identity
 
-**RAXION** is a sovereign Layer-1 blockchain (Sovereign SVM Rollup on Solana) that proves AI inference quality mathematically — replacing human subjective consensus with cryptographic proofs.
+**RAXION** is a Sovereign SVM Rollup settled on Solana that proves AI inference quality mathematically — replacing human subjective consensus with cryptographic proofs.
 
 **Core thesis**: Bittensor's failure is not an implementation problem. It is an axiom problem. Any system with a human in the inference evaluation loop inherits the Oracle Problem. RAXION removes the human entirely.
 
@@ -16,15 +16,15 @@
 
 ## Current Phase
 
-**Phase 0 — Genesis (Q1 2026)**
+**Phase 1 — Devnet (Q2 2026)**
 
 Active work:
-- Whitepaper v1.0 complete ✅
-- Python PoC: validate convergence between 2 architectures on 100+ queries
-- RISC Zero: basic proof-of-execution for simple model
-- Repository setup with contributor-ready issues
+- PoIQ v0.1 on-chain path and deterministic challenge flow
+- Runtime cognitive extensions and SDK stabilization
+- RISC Zero embedding commitment path validation
+- Devnet explorer hardening and deployment flow
 
-**Do not** ask Claude to implement Agave fork, on-chain programs, or token mechanics yet. Those are Phase 1 (Q2 2026).
+**Do not** ask Claude to implement Testnet/Mainnet-only scope (GPU proving, full 6 challenge categories, TGE tokenomics) yet.
 
 ---
 
@@ -43,6 +43,11 @@ Read this before asking "why didn't you just...":
 | No optimistic assumptions | Cognitive consequences are irreversible; 7-day challenge windows allow harmful propagation | Optimistic rollup-style contestation |
 | Jolt for quality proofs | 10–100x faster than RISC Zero for matrix operations / embedding similarity | RISC Zero for everything |
 | α=0.4, β=0.6 weighting | Causal coherence is more robust than surface embedding similarity | Equal weighting |
+| Agent stake PDA derivation is fixed | Prevents arbitrary stake injection in slashing paths; Anchor enforces seeds/owner constraints | Free-form external stake account input |
+| Stake source-of-truth is protocol stake PDA | Financial math must use synchronized protocol-owned state; scheduler cache is non-canonical | CognitiveAccount cache or SPL token account as slash source |
+| `chronic_multiplier_milli` derived on-chain | Removes client-controlled slashing amplification vector; bounded deterministic behavior | Client-provided chronic multiplier |
+| `is_final` depends on challenge lifecycle | Enforces that challenged inferences are not final until verified pass | Marking final immediately when score ≥0.60 |
+| Q2 completion requires anti-manipulation invariants | Events alone are insufficient; deterministic challenge + stake constraints + on-chain derivation are mandatory | Declaring completion by happy-path event output |
 
 ---
 
@@ -102,8 +107,8 @@ consensus in decentralized AI with Proof of Inference Quality (PoIQ).
 
 Context files: AGENTS.md (repo structure + invariants), CLAUDE.md (this), MEMORY.md (decisions).
 
-Current phase: Phase 0 (Q1 2026) — Python PoC + basic RISC Zero integration.
-Next milestone: Devnet Q2 2026.
+Current phase: Phase 1 (Q2 2026) — Devnet implementation and validation.
+Next milestone: Testnet preparation (Q3/Q4 2026).
 
 Key files:
 - Whitepaper: docs/whitepaper/RAXION_Whitepaper_v1.0_EN.md
@@ -201,7 +206,7 @@ Use this test fixture for CoherenceScore validation:
 
 | Term | Definition |
 |---|---|
-| **Cognitive Finality** | State where a zk-ML proof is valid and committed to Solana L1 — immutable |
+| **Cognitive Finality** | State where a zk-ML proof is valid and committed to Solana settlement layer — immutable |
 | **CoherenceScore** | 0.4×CS_semantic + 0.6×CC — epistemic coherence among 3 architectures |
 | **Cognition Thread** | Atomic unit of parallel inference — one architecture, one query, one partial proof |
 | **Cognitive Scheduler** | Decomposes queries into DAGs of parallel threads |
@@ -212,7 +217,7 @@ Use this test fixture for CoherenceScore validation:
 | **π_quality** | Quality proof — Jolt proof of CoherenceScore computation |
 | **π_poiq** | Aggregated final proof = AGGREGATE(π_exec×3, π_quality) |
 | **Dissent Queue** | Holding area for high-confidence divergent outputs awaiting challenge |
-| **Sovereign SVM Rollup** | Neural SVM executes independently; commits state roots to Solana L1 |
+| **Sovereign SVM Rollup** | Neural SVM executes independently; commits state roots to Solana settlement layer |
 
 ---
 

CONTRIBUTING.md

@@ -37,10 +37,8 @@ By participating in this project, you agree to abide by our [Code of Conduct](./
 
 ### Prerequisites
 
+- Python 3.11+ with `uv`
 - Rust 1.75+ (for core protocol)
-- Node.js 20+ (for tooling)
-- Solana CLI tools
-- Anchor CLI (for Solana programs)
 
 ### Building
 
@@ -49,14 +47,17 @@ By participating in this project, you agree to abide by our [Code of Conduct](./
 git clone https://github.com/rodrigooler/raxion.git
 cd raxion
 
+# Python environment (PoC)
+uv venv --python 3.11 .venv
+source .venv/bin/activate
+uv pip sync poc/requirements-dev.txt
+
 # Build core (Rust)
 cargo build
 
 # Run tests
 cargo test
-
-# Build Solana programs
-anchor build
+uv run pytest poc/tests/ -v
 ```
 
 ---
@@ -106,6 +107,20 @@ Open an issue with the `enhancement` label describing:
 - [ ] Documentation is updated
 - [ ] Commit messages follow guidelines
 - [ ] PR title follows conventional commits
+- [ ] No third-party source tree was vendored into this repository
+
+### Repository Hygiene (Required)
+
+- Do not commit upstream third-party source code (for example `runtime/agave` as a subtree copy).
+- Use on-demand bootstrap scripts instead:
+  - `./scripts/fetch_agave.sh` for pinned Agave checkout
+  - `./scripts/apply_rust_toolchain_patches.sh` for local cargo compatibility patches
+- Keep generated artifacts out of git:
+  - benchmark outputs in `poc/benchmarks/results/`
+  - build outputs in `target/`
+- Keep contribution focused on RAXION first-party code (`runtime/cognitive`, `programs/`, `sdk/`, `poc/`, `proofs/`).
+- Frontend contributions live in `apps/explorer` and `apps/site`.
+- Operational/deploy changes live in `ops/` and `scripts/`.
 
 ---