diff --git a/.claude/memory/alpha-hardening-navigation.md b/.claude/memory/alpha-hardening-navigation.md new file mode 100644 index 0000000..eb295bb --- /dev/null +++ b/.claude/memory/alpha-hardening-navigation.md @@ -0,0 +1,18 @@ +--- +name: alpha-hardening-navigation +description: Where the alpha-hardening plan lives, locked design decisions, and implementation order +metadata: + node_type: memory + type: project +--- + +Active workstream (started 2026-07-04): alpha hardening of the money/trust path. Full handoff at `/mnt/c/Users/popov/Downloads/neuron-tai-alpha-handoff-2026-07-04.md` (note: its "planning artifacts missing" section is stale — ADRs 0016–0019 and `.scratch/alpha-hardening/issues/` were created in commit 68e0572). + +**Navigation:** `.scratch/alpha-hardening/README.md` = index + phase order; `research-verifiable-inference.md` §8 = layered fraud scheme, §9 = build-vs-adopt; ADR-0018 = flagship fraud design; `docs/agents/issue-tracker.md` = issue conventions (active work in `.scratch//`). + +**Locked decisions (do not re-derive):** TOPLOC ADOPT (`pip install toploc`, teacher-forced prefill, one canonical precision per model); audit 5% default escalating on anomaly/low-rep/disputes; blame via on-demand per-hop activation commitments + bisection (fixes validator `_final_text_node` bug — it blames only the last hop); reputation = persisted graduated ×0.8-per-strike multiplier affecting routing + audit rate; full pending forfeiture stays the primary penalty; accounting becomes tracker-authoritative (count tokens from the proxied stream, work units from tracker-assigned spans — node self-reports are untrusted); strikes/bans/reputation must survive restart (RegistryWallet is RAM-only today); multi-tracker money fixes (C2/C3/C4/A3/H1) designed in ADR-0019 but implementation deferred. + +**Implementation order (Bucket 1):** 1) A2+C1+validator-token unified auth boundary + gossip auth (issues 02, 01, 20) → 2) A1/A5 persist strike/ban/reputation (05) → 3) C5+M1 starting credit 0 + spend cap (03) → 4) H2 tracker-authoritative accounting (04) → 5) C6 wallet binding proof (11) → fraud arc (06–10). + +**Why:** three audits agreed the alpha blockers are unauthenticated gossip (anyone can inject billing events), the free-credit faucet, and ephemeral bans. +**How to apply:** work test-first per issue acceptance criteria; use `.venv`; `cryptography` belongs in node deps (wallet.py imports it — causes many of the 24 "failures" in a fresh env). See [[project-status]] and [[autonomous-work-style]]. diff --git a/.claude/memory/project-status.md b/.claude/memory/project-status.md index bf7859a..3e4a7b9 100644 --- a/.claude/memory/project-status.md +++ b/.claude/memory/project-status.md @@ -27,6 +27,8 @@ Suite: 222 passed, 3 skipped (openai/langchain packages missing in .venv — pre Planning complete in `.scratch/alpha-hardening/`: research report, ADRs 0016–0019, 22 issue files, README + handoff. **Bucket 1 trust-boundary blockers** (auth, persistence, starting credit, accounting, wallet binding) are next before fraud arc (TOPLOC, bisection, reputation routing). Prod audit thresholds gated on issue 21 (honest-noise calibration corpus). +Historical handoff note: `/mnt/c/Users/popov/Downloads/neuron-tai-alpha-handoff-2026-07-04.md` is useful for navigation and original audit context, but it predates the completed `.scratch/alpha-hardening/` planning artifacts. Treat its "missing ADR/issues/README" statements as stale; prefer `.scratch/alpha-hardening/README.md` and `.scratch/alpha-hardening/handoff.md` for current task order. + ## Windows CUDA node (working as of 2026-07-01) - miniforge3 base env, torch 2.7.1+cu118, torchvision 0.22.x+cu118 - RTX 4060 Laptop GPU, 8 GB VRAM, benchmark index ~11,200 diff --git a/.scratch/alpha-hardening/README.md b/.scratch/alpha-hardening/README.md index dca505d..4758d6c 100644 --- a/.scratch/alpha-hardening/README.md +++ b/.scratch/alpha-hardening/README.md @@ -26,17 +26,18 @@ Locked scope: one settlement tracker, open node join, devnet mock-USDT, reputati ## Recommended implementation order -**Implement Bucket 1 first.** Fraud arc depends on **auth (01–02, 20)** and **persistence (05)**. +**Implement Bucket 1 first.** Fraud arc depends on **auth foundation (02 + 20)**, **hive gossip enforcement (01)**, and **persistence (05)**. ### Phase 1 — Trust boundary (alpha blockers) | Order | Issue | ID | Depends on | |---|---|---|---| -| 1 | [Unified auth + gossip auth](./issues/02-a2-unified-auth-boundary.md) + [C1 gossip](./issues/01-c1-gossip-auth.md) + [Validator service token](./issues/20-validator-service-token.md) | A2, C1, — | — | -| 2 | [Persist strike/ban/reputation](./issues/05-a1-a5-persist-strike-ban-reputation.md) | A1/A5 | 02 | -| 3 | [Starting credit 0 + spend cap](./issues/03-c5-starting-credit-zero.md) | C5, M1 | 02 | -| 4 | [Tracker-authoritative accounting](./issues/04-h2-tracker-authoritative-accounting.md) | H2 | 02 | -| 5 | [Wallet binding proof](./issues/11-c6-wallet-binding-proof.md) | C6 | 02, 03 | +| 1 | [Unified auth boundary](./issues/02-a2-unified-auth-boundary.md) + [Validator service token](./issues/20-validator-service-token.md) | A2, — | — | +| 2 | [C1 hive gossip auth enforcement](./issues/01-c1-gossip-auth.md) | C1 | 02 | +| 3 | [Persist strike/ban/reputation](./issues/05-a1-a5-persist-strike-ban-reputation.md) | A1/A5 | 02 | +| 4 | [Starting credit 0 + spend cap](./issues/03-c5-starting-credit-zero.md) | C5, M1 | 02 | +| 5 | [Tracker-authoritative accounting](./issues/04-h2-tracker-authoritative-accounting.md) | H2 | 02 | +| 6 | [Wallet binding proof](./issues/11-c6-wallet-binding-proof.md) | C6 | 02, 03 | ### Phase 2 — Fraud arc (after Phase 1) @@ -67,14 +68,14 @@ Locked scope: one settlement tracker, open node join, devnet mock-USDT, reputati | [17 Duplicate US-020 dedup](./issues/17-doc-duplicate-us020-dedup.md) | | [18 Operational runbooks](./issues/18-doc-operational-runbooks.md) | | [19 Cryptography + test env](./issues/19-doc-cryptography-test-env.md) | -| [22 MEMORY + project-status index](./issues/22-doc-memory-project-status.md) | +| [22 MEMORY + project-status index](./issues/22-doc-memory-project-status.md) (done) | | [21 Honest-noise calibration corpus](./issues/21-honest-noise-calibration-corpus.md) (ops; prod gate for audits) | ## First 3 to implement -1. **01 + 02 + 20** — Gossip auth + unified auth boundary + validator service token (unblocks financial endpoints) -2. **05** — Persist strike/ban/reputation (penalties must survive restart) -3. **03** — Starting credit 0 + funded-account gate (closes free-credit faucet) +1. **02 + 20** — Unified auth boundary + validator service token (shared helper and roles) +2. **01** — Apply hive auth to billing/accounts/stats gossip endpoints +3. **05** — Persist strike/ban/reputation (penalties must survive restart) ## Research anchor diff --git a/.scratch/alpha-hardening/handoff.md b/.scratch/alpha-hardening/handoff.md index 6b94fd4..c44246c 100644 --- a/.scratch/alpha-hardening/handoff.md +++ b/.scratch/alpha-hardening/handoff.md @@ -67,9 +67,9 @@ See `.scratch/alpha-hardening/README.md` for full table. **First 3:** -1. **01 + 02 + 20** — Gossip auth + unified auth boundary + validator service token -2. **05** — Persist strike/ban/reputation -3. **03** — Starting credit 0 + funded-account gate +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. diff --git a/.scratch/alpha-hardening/issues/01-c1-gossip-auth.md b/.scratch/alpha-hardening/issues/01-c1-gossip-auth.md index 5059720..2b9ebc9 100644 --- a/.scratch/alpha-hardening/issues/01-c1-gossip-auth.md +++ b/.scratch/alpha-hardening/issues/01-c1-gossip-auth.md @@ -14,7 +14,7 @@ Add authenticated peer identity to all tracker gossip mutation endpoints. Today - `packages/tracker/meshnet_tracker/billing.py` — `apply_events` (~301–311) - `packages/tracker/meshnet_tracker/accounts.py` — `apply_events` (~220–226) -Implement per ADR-0017 §3: shared hive HMAC (body + timestamp) or mutual TLS between configured tracker peers. Reject unauthenticated gossip with 401. +Implement per ADR-0017 §3 using the auth helper/config from issue 02: shared hive HMAC (body + timestamp) or mutual TLS between configured tracker peers. Reject unauthenticated gossip with 401. **Note:** `/v1/gossip` (node throughput fan-out, `server.py` ~1331) is **not** in scope for this issue — see ADR-0017 §3 out-of-scope note. @@ -22,7 +22,7 @@ Implement per ADR-0017 §3: shared hive HMAC (body + timestamp) or mutual TLS be 1. Red: unauthenticated POST to `/v1/billing/gossip` applies a credit event today — test must fail after fix. 2. Red: authenticated peer with valid HMAC applies events; invalid/missing auth returns 401 and `applied: 0`. -3. Green: implement verifier + config (`--hive-secret` or peer cert paths). +3. Green: wire the issue-02 verifier/config (`--hive-secret` or peer cert paths) into the three hive mutation endpoints. ## Acceptance criteria @@ -38,4 +38,4 @@ Implement per ADR-0017 §3: shared hive HMAC (body + timestamp) or mutual TLS be ## Blocked by -None — implement alongside or immediately before `02-a2-unified-auth-boundary.md`. +- `02-a2-unified-auth-boundary.md` — owns shared auth middleware/config. Implement in the same PR if simpler. diff --git a/.scratch/alpha-hardening/issues/02-a2-unified-auth-boundary.md b/.scratch/alpha-hardening/issues/02-a2-unified-auth-boundary.md index 8236e61..4ca1c28 100644 --- a/.scratch/alpha-hardening/issues/02-a2-unified-auth-boundary.md +++ b/.scratch/alpha-hardening/issues/02-a2-unified-auth-boundary.md @@ -4,7 +4,7 @@ Status: ready-for-agent ## What to build -Replace header-presence stubs with a single auth middleware that resolves API keys, admin sessions, validator service tokens, and hive peer identity. Close leaks on financial and operator endpoints. +Replace header-presence stubs with a single auth middleware that resolves API keys, admin sessions, validator service tokens, and hive peer identity. Close leaks on financial and operator endpoints. This is the auth foundation issue; issue 01 should only apply hive auth to gossip endpoints once the helper exists. **Code refs:** @@ -16,7 +16,7 @@ Replace header-presence stubs with a single auth middleware that resolves API ke - `packages/tracker/meshnet_tracker/server.py` — `_session_account` (~2468+), `_handle_admin_accounts` (~2588–2608) — H4 - `packages/tracker/meshnet_tracker/accounts.py` — `session_account()`, `create_session()` only (session store; not handler wiring) -Per ADR-0017 §4: forfeit → validator or admin; benchmark → admin; billing summary/settlements/registry wallets → admin session. Forfeit validator identity: see `20-validator-service-token.md`. +Per ADR-0017 §4: forfeit → validator or admin; benchmark → admin; billing summary/settlements/registry wallets → admin session. Include the validator service token shape from `20-validator-service-token.md` in the same implementation if practical. ## Test-first @@ -27,6 +27,7 @@ Per ADR-0017 §4: forfeit → validator or admin; benchmark → admin; billing s ## Acceptance criteria - [ ] Single `_require_auth(role=...)` (or equivalent) used by all privileged handlers +- [ ] Shared auth config supports admin sessions, validator service token, and hive peer HMAC/mTLS - [ ] Forfeit accepts only validator service token or admin session — not arbitrary Bearer strings - [ ] Financial read endpoints require admin session (alpha posture) - [ ] Benchmark write/read require admin or service token @@ -38,8 +39,8 @@ Per ADR-0017 §4: forfeit → validator or admin; benchmark → admin; billing s ## Related -- `20-validator-service-token.md` — validator service token format, rotation, forfeit auth +- `20-validator-service-token.md` — checklist for validator service token format, rotation, forfeit auth ## Blocked by -- `01-c1-gossip-auth.md` (shared auth config) +None. This issue should land before `01-c1-gossip-auth.md`. diff --git a/.scratch/alpha-hardening/issues/04-h2-tracker-authoritative-accounting.md b/.scratch/alpha-hardening/issues/04-h2-tracker-authoritative-accounting.md index 86e1f85..faa4333 100644 --- a/.scratch/alpha-hardening/issues/04-h2-tracker-authoritative-accounting.md +++ b/.scratch/alpha-hardening/issues/04-h2-tracker-authoritative-accounting.md @@ -4,7 +4,7 @@ Status: ready-for-agent ## What to build -Stop trusting node-reported usage for billing. The tracker already proxies responses — count tokens from the proxied stream/body and compute work units from the **route it constructed**, not node declarations. +Stop trusting node-reported usage for billing. The tracker already proxies responses — use tracker-observed response data and request limits to cap billable tokens, and compute work units from the **route it constructed**, not node declarations. **Code refs:** @@ -17,13 +17,14 @@ Accounting fraud = inflating tokens or shard span. Per ADR-0018 §5. ## Test-first -1. Red: mock upstream returns inflated `usage.total_tokens` in body but tracker bills that value — test expects tracker-measured count. +1. Red: mock upstream returns inflated `usage.total_tokens` in body but tracker bills that value — test expects the tracker to cap billable tokens from observed stream chunks or request bounds. 2. Red: node registers false `shard_end`; billing uses tracker route span, not registration field alone. 3. Green: authoritative counters; ignore node-reported work units on charge path. ## Acceptance criteria -- [ ] Token count for billing derived from tracker-parsed proxy response — **prefer tracker-measured stream chunk count**; when upstream `usage.total_tokens` is present, use the **minimum** of tracker count and node-reported value (cap inflated node usage) +- [ ] Streaming token count uses tracker-observed chunks/tokens; upstream `usage.total_tokens` can only lower or match that observed count, never inflate it +- [ ] Non-streaming token count caps upstream `usage.total_tokens` by tracker-known request bounds (`max_tokens`, and prompt estimate if available); exact tokenizer-backed counts are deferred unless already available locally - [ ] Work units = tracker-computed layer span per hop at route build time (~1781–1782) - [ ] Nodes cannot increase payout by lying about shard range mid-request - [ ] Integration test: malicious node metadata does not inflate `charge_request` shares diff --git a/.scratch/alpha-hardening/issues/06-fraud-toploc-integration.md b/.scratch/alpha-hardening/issues/06-fraud-toploc-integration.md index 16472ca..d10efe2 100644 --- a/.scratch/alpha-hardening/issues/06-fraud-toploc-integration.md +++ b/.scratch/alpha-hardening/issues/06-fraud-toploc-integration.md @@ -6,12 +6,12 @@ Status: ready-for-agent Adopt [TOPLOC](https://github.com/PrimeIntellect-ai/toploc) (MIT, `pip install toploc`) for activation fingerprint commit and verify. Replace string-equality validator checks with teacher-forced prefill + TOPLOC tolerance matching. -**Estimated effort:** 2+ sessions — split into subtasks below without separate issue files. +**Estimated effort:** 2+ sessions. First landing should be the validator-only TOPLOC primitive and docs; node runtime commitments/on-demand capture can follow in issue 07 if this grows. | Subtask | Owner package | Deliverable | |---|---|---| | Validator audit primitive | `packages/validator/` | Teacher-forced prefill, TOPLOC verify, unit tests with stub tensors | -| Node runtime commitments | `packages/node/` (if prover-side) | On-demand activation fingerprint generation on audit-selected requests | +| Node runtime commitments | `packages/node/` (if prover-side) | On-demand activation fingerprint generation on audit-selected requests; move to issue 07 if it blocks the validator primitive | **Code refs:** diff --git a/.scratch/alpha-hardening/issues/08-fraud-reputation-model-persistence.md b/.scratch/alpha-hardening/issues/08-fraud-reputation-model-persistence.md index 3b6125e..5a417cb 100644 --- a/.scratch/alpha-hardening/issues/08-fraud-reputation-model-persistence.md +++ b/.scratch/alpha-hardening/issues/08-fraud-reputation-model-persistence.md @@ -17,13 +17,13 @@ Implement graduated reputation per ADR-0018 §6: score derives only from tracker ## Test-first -1. Red: no reputation field — add schema + default 1.0 for new wallets. -2. Green: clean audit +0.05 (tunable); failed audit −0.3 and strike; three strikes → ban persisted. +1. Red: persisted reputation/strike fields from issue 05 are ignored by scoring/routing today. +2. Green: clean audit +0.05 (tunable); failed audit −0.3 and strike; three strikes → ban persisted via issue-05 fields. 3. Inactivity decay after N days without completed jobs. ## Acceptance criteria -- [ ] `reputation_score` persisted in registry SQLite (issue 05) +- [ ] Uses `reputation_score` and strike/ban fields persisted by issue 05; does not introduce a second schema path - [ ] Audit pass/fail updates score with documented deltas - [ ] Strike applies ×0.8 multiplier to routing weight (separate from forfeiture amount) - [ ] Ban at 3 strikes; probation job count still enforced diff --git a/.scratch/alpha-hardening/issues/17-doc-duplicate-us020-dedup.md b/.scratch/alpha-hardening/issues/17-doc-duplicate-us020-dedup.md index 7a71e41..e69e099 100644 --- a/.scratch/alpha-hardening/issues/17-doc-duplicate-us020-dedup.md +++ b/.scratch/alpha-hardening/issues/17-doc-duplicate-us020-dedup.md @@ -1,4 +1,4 @@ -Status: ready-for-agent +Status: ready-for-human # 17 — DOC: Duplicate US-020 issue dedup @@ -20,4 +20,4 @@ Resolve numbering collision without losing history. ## Blocked by -Human approval for renumbering +Human approval for renumbering. An agent may prepare the mapping note, but must not run `git mv` or rewrite cross-links until the canonical number is approved. diff --git a/.scratch/alpha-hardening/issues/19-doc-cryptography-test-env.md b/.scratch/alpha-hardening/issues/19-doc-cryptography-test-env.md index 42d7464..b18c610 100644 --- a/.scratch/alpha-hardening/issues/19-doc-cryptography-test-env.md +++ b/.scratch/alpha-hardening/issues/19-doc-cryptography-test-env.md @@ -4,7 +4,7 @@ Status: ready-for-agent ## What to build -Document and verify test/dev environment setup for wallet crypto paths. `packages/node/meshnet_node/wallet.py` uses `cryptography`; failures occur when `.venv` lacks deps. +Document and verify test/dev environment setup for wallet crypto paths. `packages/node/meshnet_node/wallet.py` uses `cryptography`; failures occur when `.venv` lacks deps. `cryptography>=41` is already declared in `packages/node/pyproject.toml`, so this issue should focus on documenting the editable-install path and only add root/dev extras if tests still import the node wallet without installing the node package. **Code refs:** @@ -14,8 +14,8 @@ Document and verify test/dev environment setup for wallet crypto paths. `package ## Acceptance criteria -- [ ] Confirm `cryptography` in node package deps; add to root/dev extras if tests import wallet without node install -- [ ] Add short **Test environment** section to `CONTRIBUTING.md` or `docs/dev/test-env.md`: use `.venv/Scripts/python.exe`, `pip install -e packages/node ...`, optional dep skips +- [ ] Confirm `cryptography>=41` remains in node package deps; add to root/dev extras only if tests import wallet without node install +- [ ] Add short **Test environment** section to `docs/dev/test-env.md` (or `CONTRIBUTING.md` if created): use `.venv/Scripts/python.exe`, `pip install -e packages/node ...`, optional dep skips - [ ] Note which tests require optional deps (`--ignore=test_openai_gateway,...`) - [ ] No unrelated production code changes diff --git a/.scratch/alpha-hardening/issues/20-validator-service-token.md b/.scratch/alpha-hardening/issues/20-validator-service-token.md index 34d79d7..a0ec7dd 100644 --- a/.scratch/alpha-hardening/issues/20-validator-service-token.md +++ b/.scratch/alpha-hardening/issues/20-validator-service-token.md @@ -4,7 +4,7 @@ Status: ready-for-agent ## What to build -Define and implement a **validator service token** distinct from client API keys and admin sessions. The validator process must authenticate when calling `POST /v1/billing/forfeit`; arbitrary Bearer strings and client API keys must be rejected. +Define and implement a **validator service token** distinct from client API keys and admin sessions. The validator process must authenticate when calling `POST /v1/billing/forfeit`; arbitrary Bearer strings and client API keys must be rejected. This is a checklist subtask for issue 02 and should normally land in the same PR as the unified auth middleware. Per [ADR-0017 §4](../../docs/adr/0017-tracker-authentication-and-authorization.md): forfeit accepts **validator service identity or admin session** only. diff --git a/.scratch/alpha-hardening/issues/22-doc-memory-project-status.md b/.scratch/alpha-hardening/issues/22-doc-memory-project-status.md index 47792b6..a7b0d80 100644 --- a/.scratch/alpha-hardening/issues/22-doc-memory-project-status.md +++ b/.scratch/alpha-hardening/issues/22-doc-memory-project-status.md @@ -1,4 +1,4 @@ -Status: ready-for-agent +Status: done # 22 — DOC: MEMORY.md + project-status alpha-hardening index @@ -8,9 +8,9 @@ Update persistent memory files so agents and humans find the alpha-hardening fea ## Acceptance criteria -- [ ] `.claude/memory/MEMORY.md` — index entry for alpha-hardening (`.scratch/alpha-hardening/`, ADRs 0016–0019, issue count) -- [ ] `.claude/memory/project-status.md` — brief alpha-hardening section: planning complete, Bucket 1 blockers next, link README -- [ ] Cross-link `.scratch/alpha-hardening/handoff.md` from README (not temp path) +- [x] `.claude/memory/MEMORY.md` — index entry for alpha-hardening (`.scratch/alpha-hardening/`, ADRs 0016–0019, issue count) +- [x] `.claude/memory/project-status.md` — brief alpha-hardening section: planning complete, Bucket 1 blockers next, link README +- [x] Cross-link `.scratch/alpha-hardening/handoff.md` from README (not temp path) ## ADR links @@ -18,4 +18,8 @@ Update persistent memory files so agents and humans find the alpha-hardening fea ## Blocked by -None — parallel with other Bucket 3 doc issues +None — completed + +## Comments + +2026-07-04 triage: already satisfied by `.claude/memory/MEMORY.md`, `.claude/memory/project-status.md`, and `.scratch/alpha-hardening/README.md`.