hunters

name

hunters

description

Use when launching, re-dispatching, or handing over the decimal_scaled background "hunter" agents — the adversarial golden-input hunters (theoretical / competitor / internal lenses), the perf-opportunity hunter, the perf-research hunter, and algorithm candidate-writers. Covers the dispatch protocol, the hard rules (no cargo/bench by agents, cleanroom licensing, no background daemons), the come-back-resend loop, the manifests, the bench seams, and copy-paste launch-prompt skeletons.

Hunters

Background-agent patterns for hardening + speeding up decimal_scaled. They divide into correctness hunters (find inputs that break the 0.5-ULP guarantee) and performance hunters (find/realise speedups). All share ONE model.

The model (the one rule)

Agents PRODUCE; the coordinator BENCHES, SELECTS, and WIRES. Benchmarking cannot be parallelised (concurrent benches skew every number — run on a quiet machine), so agents never bench. Agents generate golden-input rows, draft candidate algorithms, or research papers; the coordinator runs the benches, runs the (meaner) golden, picks winners, and wires them into policies.

Hard rules for EVERY hunter (copy into every prompt)

• NO cargo by agents — no cargo test / cargo bench / cargo build. The ONE exception: an algorithm-WRITER agent may cargo check (compile-only), sparingly. All testing + benching is the coordinator's. (Why: agents run on the user's machine; the owner watches the process monitor and blocks cargo/perf load. See [[feedback_agents_no_cargo]].)
• NO background / long-running processes — everything FOREGROUND, finish within the run. Never run_in_background, never a generator daemon / until loop / Start-Sleep. A completed agent ORPHANS its background children (they keep running untracked, don't show in the coordinator's TaskList, only in the Background-tasks UI). The coordinator drives long runs via the come-back-resend loop instead.
• LIGHT on resources — bounded chunks (~10–15 min foreground), modest CPU, or you get blocked.
• Cleanroom licensing — crate is MIT/Apache. Implement from the PUBLISHED PAPER / mathematical description; cite it. NEVER read or adapt GPL/LGPL source — GMP, MPFR, FLINT, Arb are off-limits as code (their papers are fine). See [[feedback_license_compatible_only]].
• No AI attribution — plain git commit -m, no Co-Authored-By, no 🤖, nothing about AI/Claude in commits/comments/code/docs. (Agents have repeatedly slipped a trailer in — the coordinator must scan git log <base>..<branch> --format=%B | grep -iE "co-authored|🤖|claude" before merging, and re-commit clean if found.)
• Commit on the worktree branch, NO push; the coordinator merges/wires. research/ is git-ignored (private notes); never reference it from src/.

Come-back-resend loop (how exhaustive coverage happens without daemons)

Each hunter does a BOUNDED chunk, COMMITS per unit, updates a manifest, and RETURNS with progress + what remains. The coordinator re-dispatches via SendMessage({to: <agentId>, message: "next chunk"}) — a completed agent resumes on its same worktree with the manifest intact. Repeat until the manifest is complete. Chunk size: ~5 cells/round for expensive near-tie hunts, ~15 for cheap wide-tier cells. Manifests live in tests/golden/.<lens>_done (golden) or research/.perf_*_done (perf).

⚠ COORDINATOR — THE LOOP ONLY ADVANCES IF YOU RE-SEND. READ THIS ON HANDOVER. A hunter is NOT "done" when it returns a chunk report — it is waiting for you to send it back out. When you get a <task-notification … status=completed> for a hunter (a golden lens or a perf hunter), the standing action is: read its report (rows/cells done + remaining count), then immediately SendMessage({to: <agentId>, message: "next chunk — continue from your manifest, ~N units, same protocol"}). The agent resumes on its worktree from the manifest. If you forget, the exhaustive sweep silently stalls with no error. Keep re-sending until the agent reports its manifest is complete (e.g. golden .adversarial_done covers all 264 cells). The only time you do NOT re-send is when the manifest is finished, or the work is genuinely complete (e.g. internal golden swept all 13 tiers), or it's a one-shot candidate-writer (those return a candidate, not a chunk — you bench+wire instead of re-sending). When in doubt, re-send. Inflight agentIds + their next-chunk are the most important thing to carry across a handover/compaction.

The correctness hunters (adversarial golden inputs)

Goal: BREAK the 0.5-ULP guarantee — find inputs whose correctly-rounded result a finite-precision kernel mis-rounds. They generate <input_raw>\t<floor_raw>\t<cls> rows (cls = Z exact / L <0.5 / E tie / G >0.5) via the TRUSTED oracle scripts/gen_golden_precision.py (+ the chunked deep driver scripts/gen_golden_adversarial_deep.py), append-only + dedupe to tests/golden/<fn>_d<N>_s<S>.txt, which tests/ulp_strict_golden.rs picks up automatically. Oracle MUST be correct (adaptive mpmath precision; drop anything that won't classify). Three lenses:

• theoretical (black box — does NOT read src/): math reasoning + hardest-to-round LITERATURE (Lefèvre–Muller worst cases, Kahan TMD, CORE-MATH, SLZ) + a deep near-tie probe. Worst-case family found: sqrt (c·10^k)²+ε → |frac−0.5|≈6.25e-30.
• competitor: harvest INPUT VALUES (not code) that broke other libs (MPFR worst-case tables, glibc/CORE-MATH bugs, rust-decimal/JDK/Python decimal issues), recompute our oracle. (Loria decimal64 sin/cos/log tables are WebFetch-blocked — highest-value untapped source.)
• internal (white box — reads src/): target our code's weak spots (Tang/Series band edges, native sqrt/cbrt round-step + work-width W overflow edges, argument-reduction cutoffs). Found: cbrt exact-tie branch is mathematically dead; GUARD_NARROW=10 vs doc 14. Status (2026-05-24): all 66 priority cells (D18/D38/D57) deep-swept; theoretical mid wide-tier sweep; all 13 tiers have an adversarial pass. NOTE: mul/div/rem are exact ops covered by sanity_golden (not the mpmath oracle). The D57 forward-trig Tang band (scales 44–56) has NO in-band golden table — needs a NEW table + harness wiring (coordinator action, not an agent's).

The performance hunters

• perf-opportunity hunter — systematically sweeps EVERY int + decimal function × all tiers/scales, reads routing + kernels, flags slow patterns (Series fallbacks, missing fast-paths, u64- vs u128-limb wide mul, excessive Newton iters / poor seeds, redundant work, where 0.4.4 was faster via git show v0.4.4:...), ledgers research/2026_05_24_perf_opportunities.md + research/.perf_hunt_done, drafts top candidates. Complements the GHA bench (which says WHAT regressed) by finding WHY + candidates across ALL cells.
• perf-research hunter — math papers / mathematician blogs / competitor techniques for faster algorithms (Brent 1976 AGM ln/exp; fast hyperbolics from a single exp; Zimmermann Modern Computer Arithmetic + Karatsuba Square Root paper; Payne–Hanek reduction), CLEANROOM, drafts candidates, ledger research/.perf_research_done.
• policy-range hunter — finds the range each algorithm is most performant in, i.e. systematically VALIDATES + re-tunes every policy select threshold / arm boundary (the recurring [[feedback_validate_selects_with_compare_all]] discipline — e.g. the KARATSUBA_THRESHOLD=256 that meant Karatsuba never engaged). The algorithim-optimiser skill describes the technique (the Select/ByValue/ByShape seam + the ab_microbench harness); this hunter applies it across all policies. It cannot bench (agent rule), so its deliverable is: for each int + decimal policy with a multi-arm select or threshold, the CROSSOVER question (which algo/arm wins over which (N,SCALE) / operand-length range), a flag on any unvalidated/inherited/suspect threshold, and — where the A/B seam doesn't exist yet — the wired bench arm (export the candidate arms via __bench_internals + a benches/micro/*_ab.rs) READY for the coordinator to run. Ledger research/.policy_range_done. The coordinator then runs the A/Bs on a quiet machine, finds the crossover, and re-tunes the threshold in the policy.
• candidate-writer — one focused algorithm candidate for a specific regression (diagnose + draft, cargo check only). Writes a new file under algos/, doc-headed // candidate: <what>, not wired, #[allow(dead_code)], declared in mod.rs, with a #[cfg(test)] bit-identity test it does NOT run. Reports the diagnosis + proposed wiring. Delivered so far: hypot_u128_fast (wired, hypot_D38 now 3× faster than 0.4.4), narrow as_i128/from_i128 non-limb fast path (wired), cbrt_native_fast_a (0.4.4 full-radicand f64 seed — the ~2× cbrt_D57/D76 fix, awaiting bench+wire), sum_sq_comba, sqr_full, cbrt_u128_fast, plus a wide exp/hyperbolic candidate (the 12× sinh/cosh/tanh regression).

Coordinator side (what only you do)

• Bench seams (benches/micro/, run with --features "wide bench-alt"): mul_div_native_ab (narrow mul/div), root_kernel_ab (sqrt/cbrt D57+), hypot_ab (hypot), int_unary_kernel_ab (sqr/pow/isqrt/icbrt), mul_kernel_ab (Karatsuba). For a before/after on a non-A/B path use criterion --save-baseline NAME then --baseline NAME (stash the change for the "before"). [[feedback_micro_bench_first]].
• 30-min cron polls bench-branch-compare.yml (branch vs latest crates.io tag = 0.4.4); download bench-branch-compare-merged, recompute prod-vs-branch median ratios per op·tier (the Python in the transcript), keep the regression worklist current. Do NOT babysit ci.yml (local tests gate). [[feedback_84_optimization_loop]], [[feedback_validate_selects_with_compare_all]].
• Integrate adversarial rows: merge the lenses' worktree branches (dedupe per table), then run the now-meaner ulp_strict_golden — any kernel mis-round on a mean row surfaces as a hard failure (the win). Surface failures as found bugs; fix the kernel or investigate the oracle.
• Wire a winning candidate: bring its file in (git checkout <branch> -- <file>, re-commit clean — no trailer), bench at the seam, golden-gate (full ulp_strict_golden 264+ delta==0; hypot_accuracy for hypot which golden doesn't cover), then flip the policy select/dispatch arm. Mind the dead-code marker removal.

Launch-prompt skeleton (fill the lens/task)

<LENS/TASK> agent for decimal_scaled, branch release/0.5.0 (dispatched into your own isolated worktree). STEP 0 (NON-destructive): verify a tip-only file exists in your worktree, STOP and report if absent — do NOT fetch/reset/checkout to fix a base. <MANDATE>. RESOURCE RULES: no cargo (algo-writers: cargo check only); no background/long-running jobs (foreground, finish this run); minimal CPU — else you get BLOCKED. Cleanroom (paper not GPL/LGPL code). Maintain manifest <.X_done>, bounded chunk (~N units / ~10–15 min), commit per unit on worktree, NO push, NO AI attribution. RETURN with progress + remaining; I re-send for the next chunk.