validation/detsample: Go chain-validator for reproducible sampling (Stage-1 replay)

[bonujel]

What this is

The gonka half of the two-stage inference-validation design in #1199: the Go chain-validator that replays reproducible sampling artifacts, plus the shared cross-language conformance vectors that prove it is byte-for-byte identical to the vLLM-side Python validator.

This PR is:

• Draft
• Non-enforcing, not wired into the consensus path
• Code and tests only, all under decentralized-api/internal/validation/detsample/
• Paired with the vLLM-side PR feat(sampling): reproducible deterministic sampling + validator replay (Stage-1), non-enforcing shadow path vllm#62 (deterministic-sampling-clean → main), which carries the executor, the Python validator, and the GPU evidence

It is the gonka half of a symmetric pair: vLLM produces reproducible sampling artifacts and a Python validator; this package is the Go validator the chain runs. Both reduce the same signed logprobs to the same sampled token from the same seed — verified by a common vector file.

How it works

The chain validates an inference in two stages.

• Stage 1 — Sampling-Replay (this package, full). The cheap, exact check: the validator re-derives the chain-bound RNG seed and replays the signed per-position logprobs through a deterministic decimal pipeline, checking that the same seed reduces to the same sampled token, bit for bit.
  • It never recomputes logprobs — batch composition alone flips 0–8% of honest positions, even after the executor weight fix — it replays the signed ones.
• Stage 2 — distance (metric only here). Covers the positions Stage 1 structurally can't: greedy / temperature-0 and unbounded support.
  • This package provides the metric — MAE over the top-K support — which separates honest from a wrong model by ~40–65×.
  • The threshold that turns that metric into a verdict is a policy call (Decision D) and is not in this package.

Scope of this PR. Stage 1 is complete; Stage 2 contributes the distance metric only. Signature verification of the artifact (Decision A) and wiring into consensus are out of scope. In short: this makes honest executor output replayable and provably consistent across languages, not yet enforceable.

What's in the diff

RNG and pipeline

rng.go

• Sha256CounterRNG: portable counter-mode RNG, u64 = first_8_bytes(SHA256(seed ‖ counter_be_u64)).
• Uint64Below (unbiased [0,n) via rejection sampling) and SampleCategoricalWeights over integer weights, which raises on an all-zero weight vector instead of a silent fallback.

pipeline.go

• LogprobsToWeights / DecimalSampleFromLogprobs: the decimal pipeline via cockroachdb/apd/v2.
• Fixed lexicographic token-ID string order; temperature → softmax → top_k/top_p/min_p filter → renormalize → integer weights summing to exactly 2^16 (65536).
• Exactness is what lets executor and validator reduce identically: the float path sums to [65530, 65541] and false-rejects 14–77% of honest positions; the decimal total is exactly 2^16, giving 0/128 false-rejects (E1).

Seed derivation

seed.go

• DeriveChainBoundSeed(userSeed int64, inferenceID string): Go side of fix: bind deterministic sampling seed to chain inference id vllm#56, mirroring the Python derive_chain_bound_seed byte-for-byte.
• Domain-tagged (gonka-deterministic-sampling-v1), byte-length-prefixed framing, fail-closed: rejects empty, >256-char, and non-printable-ASCII inference IDs.
• The validator derives the seed and never trusts request-controlled material.

Verdict — single position and sequence

verify.go

• VerifyPosition(Position) Result: single-position replay with a three-valued Verdict {honest, fraud, inconclusive}.
• A mismatch is fraud only when the validator could faithfully replay. An unsupported contract version or seed domain, a greedy (temp-0) position, a non-positive or unparseable temperature, or the validator's own replay error is inconclusive, never fraud — in a slashing system a false-fraud is far costlier than a missed detection.

sequence.go

• VerifySequence(SequenceRequest, []SequencePosition) SequenceResult: sequence-level Stage-1 orchestration.
• Composes the per-position seed base|pos, loops VerifyPosition, and aggregates: any Fraud → Fraud; else at least one Honest → Honest; else Inconclusive.
• Version, seed-domain, greedy, and unbounded-support gates run before any replay. Mirrors the Python verify_sequence.

Stage-2 distance metric

distance.go

• MAEDistance(executor, validator): Stage-2 distance as MAE over the signed top-K support, with sorted-key summation for byte-exact cross-language equality.
• Stage2MAEFraudThreshold is a documented placeholder (Decision D); nothing here enforces. Mirrors the Python mae_distance.

Cross-language conformance (S3)

testdata/conformance_vectors.json + conformance_vectors_test.go + sequence_conformance_test.go

• The shared vector file: RNG reference, Uint64Below sequences, float→string canonicalization, seed-derivation reference, pipeline cases, and now sequence-level and distance cases too.
• The vLLM-side PR generates and replays the same JSON. This proves Python↔Go byte-parity from the primitives up to the sequence verdict and the distance value — for example, an MAE of 0.5000000000000001 matches exactly — closing the previously-untested cross-language gap (S3).

Testing

go test ./internal/validation/detsample/ is green. Coverage:

• rng_test.go, pipeline_test.go
• seed_test.go — domain-separation and fail-closed invariants
• verify_test.go — three-valued verdict paths
• sequence_test.go — aggregation across honest / fraud / inconclusive / unbounded / greedy / version / missing-logprobs
• distance_test.go
• reject_test.go — rejection-sampling paths
• conformance_vectors_test.go, sequence_conformance_test.go — the shared vectors

Still open — do not merge for enforcement

1. Decision A — signed-artifact contract (keystone). Which fields bind into responseHash, which tokens' logprobs are signed (the filter's kept set, not a fixed K), canonicalization, filter-edge rules, and a version descriptor. SupportedContractVersion = "1.0.0" is a placeholder pending A; everything downstream depends on it.
2. Wiring into consensus. inference_validation.go does not call detsample yet. Turning it on is gated on Decision A and enforcement gating (Decision D).
3. Seed hardening (Decision C). DeriveChainBoundSeed binds (user_seed, inference_id). inference_id (via fix: bind deterministic sampling seed to chain inference id vllm#56) removes the executor-choosable hole, but user_seed stays request-controlled, leaving residual offline grinding. Bind inputs the executor cannot pick (executor address / block hash) or commit user_seed on-chain.
4. Stage-2 threshold (Decision D). The metric (MAEDistance) is settled; the threshold value, epochs, and cross-architecture CI gate are policy.
5. Tokenizer determinism. If the seed binds tokenized prompt material, tokenizer or engine drift changes the seed and false-rejects. Decide: pin the tokenizer/engine on-chain, or bind prompt_hash.

Note: RNG semantics (Decision B) are resolved to per-position independent seeding (base|pos), matched by the executor on the vLLM side.

Companion PR

The vLLM side — the executor sampling fix, the Python validator, and the GPU evidence — is gonka-ai/vllm#62.

Refs: #1199