# neuron-tai — Alpha Hardening Handoff

**Date:** 2026-07-04  
**Repo:** `D:/DEV/git.d-popov.com/neuron-tai`  
**Prior session:** Pre-release alpha audit + grilling (design locked; planning artifacts complete)

---

## 1. Mission / where we are

neuron-tai is a volunteer-GPU, pipeline-parallel LLM inference network with a working routing layer and a **broken money/trust path**. Three independent audits agreed: unauthenticated gossip, free-credit faucet, double-pay risks, ephemeral bans, and node self-reported accounting undermine alpha release. The owner locked alpha scope (single settlement tracker, open node join, devnet mock-USDT, carried-forward reputation) and a fraud/verification design (TOPLOC adoption, adaptive audits, on-demand hop bisection, persisted graduated reputation, tracker-authoritative accounting). **Research and planning artifacts are complete** (ADRs 0016–0019, 22 issue files, README index). Next: implement Bucket 1 blockers test-first.

---

## 2. Locked decisions

Point to artifacts — do not re-derive from this handoff.

| Decision | Status | Reference |
|---|---|---|
| Alpha scope: one settlement tracker, open join, devnet mock-USDT, reputation carries forward | Locked | `docs/adr/0016-alpha-scope-and-known-limitations.md` |
| Two fraud types: correctness (bad output) vs accounting (inflated tokens/shard span) | Locked | Session grilling; research §8 |
| Detection: **ADOPT TOPLOC** (MIT, `pip install toploc`); teacher-forced prefill; pin one canonical precision per model | Locked | `.scratch/alpha-hardening/research-verifiable-inference.md` §8 |
| Audit rate: **5% default, not a cap**; escalate on anomaly, low reputation, disputes | Locked | Research §1.1, §6, §8 |
| Blame: **on-demand** per-hop activation commitments + bisection to first divergent hop (Verde/Truebit **pattern only**) | Locked | Research §1.2; ADR-0018 §3–4 |
| Reputation: graduated multiplier (×0.8-per-strike shape), persisted, affects routing + audit rate | Locked | ADR-0018 §6; `packages/validator/README.md` |
| Penalty: **full pending forfeiture** is primary hammer (19× deterrence at 5% audit); ×0.8 is routing/payout decay | Locked | Research §1.1; ADR-0018 §1 |
| Accounting: tracker authoritative — count tokens from proxied stream; work units from **tracker-assigned** shard span | Locked | ADR-0018 §5; issue 04 |
| Persistence prerequisite: strike/ban/reputation/probation must survive tracker restart | Locked | Issue 05 |
| Validator service token for forfeit | Locked | ADR-0017 §4; issue 20 |
| Honest-noise corpus before prod audit thresholds | Locked | ADR-0018 consequences; issue 21 |
| Build vs adopt: TOPLOC **ADOPT**; Verde bisection **ADAPT**; zkML/TEE **roadmap-only** | Locked | Research §9 |
| Multi-tracker money-path (C2/C3/C4/A3/H1): **design now, implement later** | Locked | `docs/adr/0019-money-path-consistency-multi-tracker.md` |
| Routing layer | **Solid** — no redesign needed | ADR-0013 |

**Existing ADRs still relevant:** ADR-0003 (historical prototype), ADR-0015 (USDT custodial settlement).

---

## 3. Artifact index (read first)

| Path | What it contains |
|---|---|
| `.scratch/alpha-hardening/README.md` | Issue/ADR index + implementation order |
| `.scratch/alpha-hardening/issues/` | 22 work items (Buckets 1–3) |
| `.scratch/alpha-hardening/research-verifiable-inference.md` | SOTA research, layered alpha scheme (§8), build-vs-adopt (§9) |
| `docs/adr/0016–0019` | Alpha scope, auth, fraud, multi-tracker design |
| `docs/agents/issue-tracker.md` | Issue file conventions |
| `packages/validator/meshnet_validator/__init__.py` | Current validator; `_final_text_node` blame bug |
| `packages/tracker/meshnet_tracker/server.py` | Auth gaps, gossip handlers, proxy accounting |
| `.claude/memory/MEMORY.md` | Agent memory index |
| Agent transcript (grilling session) | [Alpha audit grilling](4406ccbb-011a-4157-851d-b5b242bba7f7) |

### Bucket summaries

**Bucket 1 — Alpha blockers:** C1 gossip auth; A2 unified auth + issue 20 validator token; C5 starting credit; H2 tracker accounting; A1/A5 persistence; C6 wallet binding; fraud arc 06–10.

**Bucket 2 — Design deferred:** C2, C3/C4, A3, H1 (issues 12–15).

**Bucket 3 — Doc hygiene:** US-006/07/34 reconciliation (16), MEMORY index (22), runbooks (18), cryptography test env (19).

---

## 4. Recommended implementation order

See `.scratch/alpha-hardening/README.md` for full table.

**First 3:**

1. **02 + 20** — Unified auth boundary + validator service token
2. **01** — Apply hive auth to billing/accounts/stats gossip endpoints
3. **05** — Persist strike/ban/reputation

**Prod gate:** issue **21** (honest-noise corpus) before enabling production audit thresholds.

---

## 5. Open questions / deferred

| Topic | State |
|---|---|
| Multi-tracker consensus & settlement idempotency | Bucket 2 (ADR-0019) |
| `/v1/gossip` node throughput auth | Out of scope alpha — ADR-0017 §3 note |
| Seed-synchronized exact-token audits | Optional complement; depends on sampler control |
| ADR-0010 TLS everywhere | Relay TLS only in alpha; ADR amended |

---

## 6. Environment notes

| Item | Detail |
|---|---|
| OS | Windows 10 |
| Repo path | `D:/DEV/git.d-popov.com/neuron-tai` |
| Python venv | `.venv/Scripts/python.exe` |
| CUDA node | RTX 4060 8 GB; tracker registration requires `https://` |
| Secrets | Do not commit `.env.devnet`, keypairs, treasury material |

---

## 7. Suggested skills

| Skill | When |
|---|---|
| **implement** | Bucket 1 code work |
| **tdd** | All Bucket 1 fixes |
| **diagnosing-bugs** | Auth/gossip/accounting failures |
| **domain-modeling** | ADR cross-links |
| **code-review** | After each blocker milestone |

Read `.claude/memory/MEMORY.md` at session start.
