feat(alpha): complete hardening backlog

Complete the alpha-hardening Ralph task set, including tracker billing/accounting guards, validator fraud-audit primitives, wallet binding proof support, documentation runbooks, and updated tests.

Verification: .venv/bin/python -m compileall -q packages tests; .venv/bin/python -m pytest -q --tb=short (313 passed, 3 skipped, 1 failed: tests/test_mining_cli.py::test_legacy_start_without_port_uses_next_available_port because meshnet-node pid 1263451 is already listening on port 7000).

packages/validator/README.md

@@ -2,28 +2,58 @@
 
 Optimistic fraud detection (ADR-0003, penalty amended by ADR-0015): the
 validator re-runs a random ~5% sample of completed inference requests against
-a trusted reference node and, on divergence, submits a slash proof and
-forfeits the node's pending balance.
+a trusted reference node. Audit-capable events are checked by teacher-forcing
+the claimed token sequence through the reference node and verifying the
+claimed TOPLOC activation proof. Legacy events without TOPLOC metadata still
+fall back to text comparison until node-side proof capture lands.
 
 ## Why the penalty deters cheating
 
 There is no upfront stake. Settlement is periodic (US-033), so a node always
 has an unpaid **pending balance** — that balance *is* the collateral.
 
-At a sampling rate `p`, a cheater is caught on average once every `1/p`
-fraudulent jobs, so cheating is unprofitable when:
+At a sampling rate `p`, a cheater who gains `G` per fraudulent job and loses
+`L` when caught has expected value:
 
 ```
-penalty > per_job_gain / p        # p = 0.05  →  penalty > 20 × per_job_gain
+(1 - p) * G - p * L < 0
+L > ((1 - p) / p) * G        # p = 0.05  ->  L > 19 x G
 ```
 
 With the production settlement period of 24h, the pending balance at any
 moment approximates a full day's earnings — hundreds to thousands of jobs —
-which is far above the 20× bar. Each catch also records a strike; three
+which is far above the 19× bar. Each catch also records a strike; three
 strikes ban the wallet (registration rejected, excluded from routes, unpaid
 pending never settled), and the probationary period (first N jobs unpaid)
 makes re-entry with a fresh wallet costly.
 
+## TOPLOC audit contract
+
+The validator expects audit-capable events to carry:
+
+- `claimed_token_ids`: the final token sequence claimed by the prover.
+- `toploc_proof`: compact TOPLOC proof data built from prover activations.
+
+On audit the validator calls the reference node's `POST /v1/audit/toploc`
+endpoint with the original messages plus `claimed_token_ids`. The reference
+node must run a teacher-forced prefill over exactly that token sequence and
+return the activations for TOPLOC verification. It must not free-generate a
+second answer for audit.
+
+Canonical audit parameters for the current alpha preset are:
+
+```
+dtype = "bfloat16"
+quantization = "bfloat16"
+decode_batching_size = 32
+topk = 8
+skip_prefill = true
+encoding = "base64"
+```
+
+Production audit thresholds remain gated on the honest-noise calibration
+corpus in issue 21.
+
 Two operational notes:
 
 - Shortening the settlement period shrinks the collateral. Period changes
@@ -44,3 +74,27 @@ ValidatorProcess(
 
 Remote validators can instead call the tracker's privileged
 `POST /v1/billing/forfeit` endpoint (non-empty Authorization header).
+
+## Reputation-weighted audit rate (ADR-0018 §1, §6-7)
+
+`sample_rate` is a flat coin flip: every wallet audited at the same rate.
+Pass `audit_sampler=AdaptiveAuditSampler(...)` instead to make the audit
+probability a function of each wallet's tenure and reputation — newcomers
+and low-reputation wallets sampled at 20–30%, veterans in good standing
+floor at ≥2% — while a running budget balance keeps the fleet-wide realized
+rate anchored to `AuditRateConfig.target_rate` (default 5%) regardless of
+the wallet mix. Passive tripwires (`detect_output_tripwire`) bump only that
+one request's odds; they never strike, ban, or affect other wallets' rates.
+
+```python
+from meshnet_validator import AdaptiveAuditSampler, detect_output_tripwire
+
+ValidatorProcess(
+    contracts=contracts,
+    reference_node_url="http://...",
+    audit_sampler=AdaptiveAuditSampler(random_seed=42),
+)
+```
+
+When `audit_sampler` is set, `sample_rate` is ignored — the sampler decides
+per event, keyed on whichever route wallet has the lowest reputation.