Machine-readable runtime-profile/packaging/output matrix the CLI vendors;
wasm and os-isolation+wasm supported, microvm and rvm-native planned with
explicit isolation claims per ADR-285.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01ParP55bZs2iTGEGvpnUecx
Path-filtered workflow: npm install/build/test for the CLI on
ubuntu/windows/macos, cargo test + clippy -D warnings + fmt check for
the crate. Tolerates the pending forge->rvforge package rename and
skips gracefully while directories are still landing.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01ParP55bZs2iTGEGvpnUecx
One canonical RVF to signed platform installers: @ruvector/forge CLI,
hosted build service, Tauri RVF Reader, rvm-* backend crates. Derived
from the rvForge product directive; requirements.md is the source of
truth for the feat/rvf-forge build-out.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01ParP55bZs2iTGEGvpnUecx
Three ADRs implemented and hardened across five rounds of adversarial review, plus the fixes that review surfaced.
**ADR-280 — durable RVF metadata.** Delta-encoded generations with a snapshot every 32. The first implementation wrote a full snapshot per commit and replayed every one at open: 600 commits produced a 725 MiB file that could no longer be opened, with no repair path. Now 241 KB of META payload for the same workload, opening in ~4 ms. Review also closed: derive-children that could not be reopened, an 80-byte file driving a 512 MiB allocation, delete() rollback leaving in-memory tombstones that bricked the artifact, ten BufWriter sites discarding flush errors before sync_all, corrupt mid-chain deltas made unopenable (now recovers the longest valid prefix), and an ordering bug where recovery pruning committed without its re-anchoring snapshot so `rvf ingest` printed a repair warning and then destroyed the file.
**ADR-281 — role-aware embeddings.** Query/passage routing with an attested embedding-space identity. Review found the space id hashed CARGO_PKG_VERSION, so a routine version bump would have rejected every persisted corpus and invalidated every cache key — with the test suite structurally blind to it. Now keyed on a dedicated format revision with a golden-id test. Also: three constructors that failed unconditionally with ten unmigrated callers, prompt templates applied from the attested identity rather than hardcoded strings, and ApiEmbedding no longer bypassing templating.
**ADR-282 — nightly research quality gate.** Review found the gate had never completed a single run: the candidate checkout was shallow so its git diff always failed, and a jq quoting bug made the override path dead code. Check-run queries were unpaginated — on a real main commit 8 of 22 failures were invisible, so a red base could be certified green. Schemas are now load-bearing with a hashed dependency closure.
**CI note.** The two red checks are both pre-existing on main, not regressions from this branch: `Tests (core-and-rest)` routinely exceeds its 4-hour window, and `Hooks CI` has failed on main since 2026-08-02 (and in May) on `cp -r node_modules $GITHUB_WORKSPACE/npm/packages/cli/` in hooks-ci.yml — this branch's one-line version sync merely re-triggered its path filter. 72 checks pass.
Follow-ups filed and not blocking: #770, #771, #772.
🤖 Generated with [claude-flow](https://github.com/ruvnet/claude-flow)
Codifies the shipped RVF v1 wire format as the single normative contract: tail-discovered 4096-byte root manifest (no offset-zero header), exact little-endian magic wire bytes (segment 53 46 56 52, root 30 4D 56 52) exported as SEGMENT_MAGIC_BYTES/ROOT_MANIFEST_MAGIC_BYTES, golden byte-vector tests derived from shipped writer output (SHAKE-256 empty-input field matches the NIST vector; root CRC32C FF DD 18 14 verified), supersedes ADR-004/005 wire sections, fixes a tail_scan comment documenting the wrong anchor byte and doc pseudocode that compared wire bytes to literal ASCII, adds a pinned-action CI gate over rvf-types/rvf-wire. No wire bytes changed — existing artifacts, hashes, signatures remain valid.
🤖 Generated with [claude-flow](https://github.com/ruvnet/claude-flow)
Research docs + target architecture for rvagent as a Hermes-class harness (metaharness + ruflo integration), ADRs 273-279, rvAgent harness repair (tool schemas wired, middleware pipeline, subagents, bootstrap, policy genome), PDX vertical-layout benchmark (not adopted), plus full adversarial code-review fix round: symlink/hard-link write-escape confinement in local tools, real HITL gating in both pipeline construction paths, Gemini parallel-tool-call and schema-compatibility fixes, panic/deadlock hardening.
CI note: Tests (vector-index) failure is the pre-existing flaky ruvector-diskann recall_trigger_holds_under_no_drift probabilistic test (untouched crate; passes 3/3 locally on this head, passed on prior run). Tests (core-and-rest) historically exceeds its window and was not required.
🤖 Generated with [claude-flow](https://github.com/ruvnet/claude-flow)
Refresh all committed Rust locks, eliminate actionable RustSec findings, make the npm graph reproducible and audit-clean, retire vulnerable optional backends, harden RuVocal production dependencies, and repair the affected publishable packages.
Closes#736.
ADR-194 is already taken on main (ruvector ONNX embedder API & throughput).
Renumber this PR's turbovec ADR to the next free number (254), matching the
canonical record on main. Keeps the fuller PR version (D1–D5 divergences table,
D3/D4 measured-milestone markers) and adds a numbering note. Updates the 13
in-crate ADR-194 references and two stray ADR-193 'future work' pointers so they
no longer resolve to the unrelated ONNX ADR.
Refs #520, #521
Add quantizer_mse_within_paper_bound: draw 400k N(0,1) samples (Box–Muller,
no new deps), quantize via the real quantize_coord path, and assert the
per-coordinate MSE for every width stays under TurboQuant's distortion bound
D_mse ≤ (√3·π/2)·4^(−b) (arXiv:2504.19874) AND within 5% of the Max-1960
Lloyd–Max optimum. A corrupted centroid level trips this far more precisely
than the existing recall>0.5 threshold.
Marks D4 done in ADR-194; updates test count to 17. The full-pipeline
inner-product bound D_prod remains future work (tracked with D5).
Adds BitWidth::Three (8-level Max-1960 optimal N(0,1) reconstruction
levels). pack/unpack, calibration, scoring, and IdMap are width-generic,
so only the centroid table + the enum arms change.
Measured (cargo run --release -p ruvector-turbovec, n=5000 uniform-random,
dim=256, k=10, no rerank, vs exact L2):
3-bit: recall@10 0.767, 112 B/vec, 9.8x compression, bias -0.0000
landing squarely between 2-bit (0.561) and 4-bit (0.879) — a useful
memory/recall midpoint (~22% smaller than 4-bit for ~0.11 recall).
Also refresh ADR-194: add the 3-bit Validation row, mark D3 done, widen
T2 to {2,3,4}, correct the test count to 16, and scope the provenance
note so the measured recall/compression/bias figures are called measured
while the FAISS-competitive claims stay attributed targets.
16 unit + 1 doc-test pass; clippy clean; new code is rustfmt-clean.
Add an explicit 'Divergences from the TurboQuant paper (arXiv:2504.19874)'
section mapping where M1 departs from the paper, so the gaps are reviewable
and the follow-ups are paper-grounded:
- D1: M1 uses a heuristic per-vector c_x scale, not the paper's provably-
unbiased two-stage MSE + 1-bit-QJL-residual estimator. Soften the T4 and
Validation wording accordingly (empirically near-unbiased, not proven).
- D2: M1 quantizes against the N(0,1) limit + empirical TQ+ calibration, not
the paper's exact d-aware Beta-optimal codebooks.
- D3: M1 ships 1/2/4-bit; paper highlights ~2.5/3.5 bpc sweet spots — add 3-bit.
- D4: assert measured distortion under the paper's closed-form bounds as a
stronger test oracle than recall > 0.5.
- D5: estimator variance deferred.
Add milestones M5 (paper-grade QJL-residual estimator) and M6 (Beta-optimal
codebooks); note what M1 already matches (norm-based L2, online ingest,
full-precision query). No code change.
- Cargo.toml: remove unused rand_distr dependency and the redundant
rand dev-dependency (rand is a normal dep for the demo bin + tests).
- Cargo.lock: drop rand_distr from ruvector-turbovec.
- ADR-194: attribute the FAISS-competitive figures to the upstream
RyanCodrai/turbovec project rather than presenting them as this
crate's measured results; point readers to the reproducible
uniform-random Validation table instead.
No code changes; 16 unit + 1 doc-test still pass, clippy clean.
- index: TurboVecIndex::add/search now return RabitqError::DimensionMismatch
in release builds instead of silently accepting/masking wrong-length
vectors (was debug_assert + unwrap_or_default).
- index: finalize() excludes zero vectors from calibration fit so they
don't bias shift/scale toward zero.
- idmap: add_with_id validates dim up front and reports the real length
(was hardcoded got: 0); add_with_ids rejects vectors/ids length
mismatch with new TurboVecError::BatchLenMismatch instead of zip-truncating.
- quantize: pack/unpack document preconditions and debug_assert code-range
and slice-length (proportionate to internal helpers; no Result churn).
- calibrate: fit debug_asserts every row has length dim.
- ADR-194 frontmatter status proposed -> accepted to match body.
Adds 4 tests (wrong-dim reject on add/search, zero-vector calibration
exclusion via self-retrieval, batch-len mismatch, idmap wrong-dim).
16 unit tests + 1 doc-test pass; clippy clean; demo unchanged.
https://claude.ai/code/session_012AzArCzBwxrJp8mUngUcH5
Research and scope a new crate adapting TurboQuant techniques from
RyanCodrai/turbovec: 2/4-bit Lloyd-Max scalar quantization, TQ+
per-coordinate calibration, length-renormalized unbiased scoring, and a
nibble-LUT FastScan SIMD kernel (AVX-512BW/AVX2/NEON). Reuses
ruvector-rabitq's Hadamard rotation + AnnIndex/VectorKernel traits and
borrows ruvllm's MSE quantizer math, closing the missing 2-4-bit FastScan
ANN regime.
https://claude.ai/code/session_012AzArCzBwxrJp8mUngUcH5
* research: add nightly survey for recall-bounded-ann
Nightly 2026-07-24: Recall-Bounded Approximate Nearest-Neighbour Search.
Establishes the RecallBoundedIndex trait and three measured Rust variants
for quality-first agent memory retrieval (search_above_threshold instead
of top-k). All 8 tests pass; acceptance gate met at recall >= 0.80.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01GyrjFPrMZCH3knQuw8QgLk
* fix recall-bounded ANN ids and search budgets
---------
Co-authored-by: Claude <noreply@anthropic.com>
* feat(diverse-beam): add ruvector-diverse-beam crate with MMR and coherence-pruned beam search
Implements three beam-search variants on a flat kNN graph:
- GreedyBeam: baseline greedy BFS (recall@10=0.816, QPS=10975 on uniform n=2500)
- MMRRerank: greedy pool + MMR post-reranking (λ=0.75, +1.67% diversity, −13.4% recall)
- CoherenceBeam: cosine-gated BFS (anti-pattern for clustered data, documented)
Also includes odd-stride entry point fix, normalised MMR scoring, and a benchmark
binary with acceptance thresholds. All 9 unit tests pass; benchmark PASS ✓.
* docs(adr): ADR-272 diverse beam ANN — MMR post-reranking and coherence-pruned beam search
Documents decision to implement ruvector-diverse-beam, measured results, two negative
results (MMR during traversal, CoherenceBeam on clustered data), and alternatives
considered (DPP, structural diversity). Status: Proposed.
* research(nightly): 2026-07-26 diverse beam ANN — README and gist
README: full 24-section research document with SOTA survey, architecture diagram,
all measured benchmark results, key findings (MMR traversal anti-pattern, coherence
cluster failure), memory model, practical/exotic applications, and future work.
gist.md: SEO-optimized public technical article targeting engineers building
RAG/agent-memory systems on vector databases.
* fix diverse beam traversal and scoring
---------
Co-authored-by: Claude <noreply@anthropic.com>
- #706: apply_micro_lora/apply_base_lora seeded their output buffer with
zeros in napi.rs, napi_simple.rs, and wasm.rs, but the Rust LoRA forward
pass has residual semantics (adds delta into the buffer). Cold queries
collapsed to the zero vector, and post-feedback queries returned only
the delta instead of input+delta. Fixed by seeding with a clone of the
input in all three binding layers. Added regression tests.
- #705: WasmBackend had no byte-level persistence. The underlying
rvf_store_export/rvf_store_open C-ABI functions already existed —
wired them into WasmBackend.exportBytes()/openBytes() and
RvfDatabase.exportBytes()/openBytes(), verified against the real
compiled .wasm binary.
- #704: NodeBackend.ingestBatch() silently dropped RvfIngestEntry.metadata
instead of forwarding it, and query() filter serialization omitted the
native parser's required valueType. Since a full field-name-to-id
design for metadata durability is a larger follow-up, applied the
issue's own suggested interim fix: ingest now throws
MetadataNotSupported instead of silently losing data. Filter
serialization now infers and includes valueType.
- #707: docs/api/NODEJS_API.md and docs/guides/ADVANCED_FEATURES.md
advertised HybridSearch/FilteredSearch/MMRSearch/ConformalPredictor as
Node exports; none are bound by crates/ruvector-node. Corrected with
explicit "not yet shipped" notes pointing at the tracking issue.
README corrections for #705/#707 (WasmRvfStore, HybridSearch docs) are
staged separately — a repo hook requires a visual design-grade ritual for
any README change that this session cannot complete (no browser/screenshot
access), so they'll follow once that's resolved.
Adds a fourth MultiVecIndex variant to ruvector-maxsim: a greedy kNN graph
over per-document centroids + multi-seed beam search + exact MaxSim rerank.
Complements the token-level HnswMaxSim with a one-node-per-document graph.
Includes the consecutive-seeding correctness fix discovered in nightly PR
#622: step-based beam seeding collapses recall when the step is a multiple
of the cluster count. Documented in graph.rs and ADR-252.
#622 produced a duplicate ruvector-maxsim crate (the name was already taken
by #569, merged 2026-06-15); rather than merge the duplicate, its unique
value is salvaged here. The public research gist from #622 remains published.
- 5 new tests (recall vs Flat, dim validation, build/empty guards) — 23/23 pass
- cargo fmt clean, cargo clippy -D warnings clean
* feat(sona): metaharness-Darwin evolves EWC++ config beyond hand-tuned SOTA
examples/darwin_ewc: applies the Meta-Harness 'freeze the model, evolve the
harness' pattern to SONA's continual-learning layer — frozen = the EWC++
algorithm (EwcPlusPlus), evolved = its EwcConfig genome (lambda schedule, Fisher
decay, auto task-boundary threshold, learning rate).
Benchmark: a single weight vector trained on a sequence of tasks (no replay,
auto-detected boundaries) — the canonical plasticity-vs-forgetting frontier.
Darwin (GA + coordinate-descent polish) evolves the genome on TRAIN task-
sequences; results reported on HELD-OUT sequences (different seeds).
Measured (deterministic), held-out: the evolved config beats EwcConfig::default()
(the crate's hand-tuned 'OPTIMIZED' values) by 35% lower final loss and 98.6%
less forgetting — a strict Pareto win (plasticity also improves), and it
generalizes to unseen task sequences. clippy -D warnings clean, fmt clean.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sona): weightAdapter gene — Darwin selects/prunes a fine-tuned adapter
Extends the metaharness-Darwin line: expose a fine-tuned adapter (e.g. a LoRA
distilled from verified SWE-bench trajectories — the 'autonomous data engine')
as a gene (which_adapter, alpha) so evolutionary selection decides whether/how
much to apply it (w_eff = w_base + alpha·Δw) instead of assuming new weights are
better. examples/darwin_weightadapter demonstrates it on two conflicting domains
with a generalizing adapter and an overfit one.
Key finding (sharpens the idea): 'selection prunes overfit adapters' holds ONLY
under per-domain evaluation. Measured (held-out, in-dist-majority eval):
overfit α=0.55 → ΔA +0.249 / ΔB -0.357 (regresses out-dist)
AGGREGATE (volume-weighted) fitness → picks the overfit adapter (silent B regression)
PER-DOMAIN (no-regression Pareto) → prunes it, keeps the generalizing adapter
So: evolve the adapter as a gene, but score it per-repository. clippy/fmt clean.
Co-Authored-By: claude-flow <ruv@ruv.net>
* docs(adr): ADR-271 metaharness-Darwin for SONA self-improvement
Documents the metaharness-Darwin-evolves-SONA architecture: EWC++ config
evolution (PR #615), the weightAdapter gene (per-domain Pareto selection of
fine-tuned adapters), the Autonomous Data Engine (execution-verified SWE-bench
trajectories -> DPO pairs), and four Ornith-1.0 borrows (immutable-boundary +
deterministic-monitor-with-exclude-from-advantage + frozen-LLM-judge-veto
reward-hacking defense; per-task-category specialization; two-stage scaffold
reward credit; staleness-weighted replay). Method-not-model: external
evolutionary vs Ornith's in-weights RL.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sona): darwin-guard reward-hacking defense (Ornith-1.0 borrow, ADR-271)
3-layer defense for evolutionary config search: (1) immutable verifier boundary
(screen is a pure fn of verifier output the candidate can't fabricate);
(2) deterministic monitor — non-finite / out-of-bounds / degenerate candidates
are EXCLUDED from selection (best_accepted), not zero-scored, so a hack can
neither win nor bias the advantage; (3) IntentJudge trait = frozen-LLM veto-only
layer. Wired into darwin_ewc: NaN/collapsed configs are excluded from the GA
ranking (also fixes the partial_cmp().unwrap() NaN-panic). 4 unit tests; benchmark
still reaches beyond-SOTA (35% lower loss, 98.6% less forgetting) unchanged.
clippy -D warnings + fmt clean.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sona): per-task-category genome router beats single global config (ADR-271)
Ornith-1.0 borrow #2 (per-category specialization): evolve a router task-class
-> genome instead of one global EwcConfig. Two continual-learning workload
classes with conflicting optima (STABLE wants high lambda / retain; VOLATILE
wants low lambda / stay plastic). Guard-screened evolution.
Measured (held-out, adequate per-class data): per-category router 0.1122 vs
single best global genome 0.1144 -> router ~1.9% better on unseen sequences,
because one config cannot serve conflicting workloads.
Honest caveat (discovered + documented): the gain REVERSES when per-class data
is scarce — a specialized config overfits while the pooled global generalizes.
Per-category routing needs enough per-category samples (Ornith's regime). ADR-271
updated; clippy/fmt clean.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sona): online auto-tuner with staleness-weighted replay (ADR-271, Ornith borrow #4)
auto_tuner module: StalenessSchedule (Ornith w(d_t): fresh<=k1, exp-decay,
drop>k2) + StalenessWindow (staleness-weighted running estimate of recent
config performance, evicts stale obs). 4 unit tests.
examples/darwin_autotuner: a (1+1)-ES that adapts a DEPLOYED EwcConfig to a
drifting workload stream (regime A -> B at the midpoint), scoring the incumbent
on the staleness window and accepting a perturbation only when it beats the
recent score. Measured: online tuner ~3% lower post-drift loss than the static
deployment config (10 accepted re-tunes). Margin is modest on synthetic regimes;
the durable win is the reusable staleness machinery + the online-adaptation
principle (a fixed offline-tuned config goes stale under drift).
Completes the four ADR-271 components. clippy --all-targets -D warnings + fmt
clean; 102 sona tests pass.
Co-Authored-By: claude-flow <ruv@ruv.net>
* feat(sona): contamination/disjointness guard in darwin-guard (weight-eft/ADR-198 borrow)
Adds the train/eval contamination guard — the gap @metaharness/weight-eft exposed
in our reward-hacking-only guard. contamination()/assert_train_eval_disjoint()
fail on any train∩eval instance-ID overlap (training/selecting on eval instances
is fake lift); filter_holdout() partitions a set disjoint-by-construction and
surfaces what was excluded. The SONA-side analog of weight-eft's
assertTrainEvalDisjoint. 2 new tests (6 total in darwin_guard).
ADR-271 updated: §3 Data Engine now cites @metaharness/weight-eft + adopts its
RLHF-correct recipe (SFT distills ALL gold incl. off-policy frontier successes;
DPO ON-POLICY cheap-vs-cheap only), and the darwin-guard borrow gains layer (iv)
the contamination disjointness guard. clippy -D warnings + fmt clean.
Co-Authored-By: claude-flow <ruv@ruv.net>
* chore(release): ruvector-sona 0.2.1 — darwin_guard + auto_tuner modules
Non-breaking minor feature release (new public modules darwin_guard,
auto_tuner). Patch bump keeps the ^0.2 requirement of all in-workspace
dependents (ruvllm, rvlite, mcp-brain, ...) satisfied.
Co-Authored-By: claude-flow <ruv@ruv.net>
---------
Co-authored-by: ruvnet <ruvnet@gmail.com>
* feat(mragent): MRAgent graph memory over RuVector with Darwin optimization
Add ADR-269 and a runnable reference implementation of MRAgent ("Memory is
Reconstructed, Not Retrieved") on RuVector, optimized by Meta-Harness Darwin
Mode under the "freeze the model, evolve the harness" invariant.
- Frozen model: deterministic Cue-Tag-Content memory substrate mirroring
RuVector hybrid (RRF) search + bounded-depth Cypher traversal semantics
(examples/mragent/agent/memory.mjs)
- Evolved harness: 10-gene reconstruction genome (cueK, efSearch, hybridAlpha,
fusion, traversalDepth, tagFanout, pruneThreshold, maxContent, rerank,
promptStrategy) in DARWIN_MUTABLE_BLOCK regions (agent/harness.mjs)
- Darwin evolution loop with mapLimit/paretoFront and ADR-150 graceful fallback
when @metaharness/darwin is absent (optimize.mjs)
- scorePolicy.ts fitness mirroring ADR-266; benchmark + probe + 7 deterministic
acceptance gates
- eval corpus with chained multi-hop "bridge" tasks so traversal depth, fan-out
and pruning are genuinely load-bearing
Runs with zero optional deps: baseline 83.3% -> evolved 100% accuracy, faster
and ~33% smaller context. Darwin discovers traversalDepth=3 (LINKED_TO*1..3).
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_017MDmEV4svuFxuDBGg8zek2
* feat(mragent): self-reconstructing graph memory, beyond SOTA (ADR-270)
Extend the MRAgent harness past the paper into calibrated, adaptive,
self-reorganizing memory, co-evolved by Darwin. Also fixes the corpus being
silently excluded by the root .gitignore data/ rule (the example was missing
its eval set).
Beyond-SOTA mechanisms (each a tunable gene Darwin evolves):
- Adaptive depth (haltConfidence): halt traversal once evidence is decisive
- Abstention + risk-adjusted utility (abstainThreshold): refuse on weak
evidence instead of hallucinating; graded on calibrated utility, not raw acc
- Consolidation/replay (agent/consolidate.mjs): store reorganizes its own
topology, laying Cue->shortcut->Content edges (RuVector self-learning GNN)
Substrate upgrades:
- Concept layer (agent/concepts.mjs): dense (concept) vs sparse (token) signals
genuinely decoupled, so hybridAlpha/fusion become load-bearing
- Hardened 24-task corpus, 6 classes (semantic/lexical/hybrid/bridge/
distractor/unanswerable) synthesized from structured signal specs
- All 12 genes proven load-bearing (some via epistatic interaction)
- Memetic optimizer: GA (mapLimit/paretoFront) + multi-start coordinate-descent
polish that reliably finds the narrow calibration optimum
Measured (deterministic, zero optional deps): baseline acc 81% / risk 0.708 /
halluc 0.13 -> evolved 100% / risk 1.000 / halluc 0.00; consolidation -25%
hops at 100% accuracy. 11 acceptance gates pass. ADR-150 compliant.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_017MDmEV4svuFxuDBGg8zek2
* feat(mragent): generalization protocol (train/test/CV) + overfit fixes
Add a held-out evaluation regime that proves the evolved harness GENERALIZES
rather than memorizing the eval set, and fix the overfitting it surfaced.
Protocol:
- Scale corpus to 60 tasks via a deterministic generator (tools/genCorpus.mjs,
npm run gen-corpus), 10 per class, difficulty-varied (1-hop AND 2-hop bridges,
1-3 ranking-distractors) so train constrains every gene
- Optimizer evolves on a class-stratified TRAIN split, selects via 3-fold
cross-validation with a variance penalty (mean - 0.5*range), and reports a
held-out TEST split it never saw
- Generalization gate = does evolution improve the unseen split
Overfit fixes uncovered by held-out eval:
- Abstention confidence now derives from the answer's RAW relevance, not its
decay^depth path score, so deep-but-relevant bridge answers aren't mistaken
for weak ones (b-test confidence 0.39 -> 0.79); abstention generalizes across
depths. Adaptive-depth halt uses the same raw-relevance signal.
- Larger difficulty-varied corpus + CV variance penalty stop the optimizer
shaving under-constrained genes (maxContent->1) to train-fragile settings
Result (held-out test, reproducible): baseline ~30% acc / risk 0.25 / halluc
0.17 -> evolved ~65% / 0.81 / 0.04 (+35pt acc, +0.56 risk). Honest ceiling
(~80%) documented: synthetic embedding noise + one global hybridAlpha can't
serve both dense- and sparse-keyed queries. 12 acceptance gates pass.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_017MDmEV4svuFxuDBGg8zek2
* feat(mragent): GPU LLM write-layer for the Darwin optimizer (local RTX 5080)
Adds the directed-proposal layer the GA lacks (ADR-260 'real Darwin write-layer
proposes leaps from failure traces'): agent/llmMutator.mjs shows a local,
GPU-served code model (qwen2.5-coder via an OpenAI-compatible endpoint) the
current genome + its failing cases and asks for improved genomes. Every proposal
is clamped to the declared gene bounds (coerceGenome) before entering the
population, so untrusted LLM output can only ever be a safe genome — never an
unsafe gene. Wired into optimize.mjs every 3rd generation; folded into the
archive so GPU candidates compete in polish + acceptance.
Fully opt-in + gracefully degrading (ADR-150): MRAGENT_LLM=off or no reachable
endpoint => identical deterministic GA+coordinate-descent run as before. Auto-
detects http://localhost:11434/v1 (ollama) by default; MRAGENT_LLM_URL/MODEL
override.
Measured (RTX 5080, qwen2.5-coder:7b): 8 genomes proposed across gens, bounds-
safe; the deterministic polish still wins on this small synthetic corpus (the
GA+grid already enumerates the optimum), so the write-layer is a no-regression
enhancement that matters on larger corpora the grid can't cover. 14/14 tests
pass (2 new coerceGenome safety tests).
Co-Authored-By: claude-flow <ruv@ruv.net>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: ruvnet <ruvnet@gmail.com>
* research: add nightly survey for spann-partition-spill
SPANN-inspired partition spilling for boundary-safe ANN (2026-06-24).
Three measured variants, zero external deps, 10 passing tests.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_015jtrAifbFHQ1YWupgjA5HH
* docs: add ADR-268 for spann-partition-spill
ADR documents the design, benchmark evidence, failure modes, migration
path, and open questions for SPANN-style partition spilling in RuVector.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_015jtrAifbFHQ1YWupgjA5HH
* docs: add nightly research README and SEO gist for spann-partition-spill
Research document with full benchmark results, ecosystem fit analysis,
practical applications, exotic applications, and production roadmap.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_015jtrAifbFHQ1YWupgjA5HH
* fix(ruvector-spann): remove nested workspace root + lint cleanup
The crate declared its own [workspace] while also being a member of the
root workspace, producing "multiple workspace roots" and turning every CI
check red (build, check, all test shards, fmt). Remove the stray
[workspace] block and the committed nested Cargo.lock, then apply
clippy --fix (sort_by -> sort_by_key) and rustfmt.
cargo build/test/clippy -p ruvector-spann now green: 10/10 tests pass.
Co-Authored-By: claude-flow <ruv@ruv.net>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: ruv <ruvnet@users.noreply.github.com>
* feat(sonic_ct): acoustic digital human workbench — Rust/WASM USCT + R3F UI
Add `sonic_ct`, a research-grade Ultrasound Computed Tomography (USCT)
simulator and reconstruction workbench.
Core (crates/sonic-ct, pure Rust, zero deps, 17 tests):
- procedural z-varying torso phantom (fat/muscle/organ shells, spine, ribs,
pelvis, liver/spleen/kidneys/aorta, heart+lungs in thorax)
- circular ring acquisition with straight-ray travel-time + attenuation
- SART time-of-flight reconstruction (1 sweep == delay backprojection)
- transparent speed-band segmentation with per-cell uncertainty
- coordinate-ascent threshold training (mean Dice ~0.30 -> ~0.63)
- RuVector-style acoustic memory: NSW vector index, longitudinal drift,
warm-start, anatomical graph-coherence checks, .rvf-style serialization
- 3-D volume sweep (truth / recon / error / confidence channels)
- mock Butterfly Embedded acquisition boundary (trait, no hardware SDK)
WASM (crates/sonic-ct-wasm): raw C-ABI cdylib (no wasm-bindgen, ~39 KB)
exposing the single-slice + progressive volume pipeline.
UI (examples/sonic-ct): React Three Fiber "Sonic Chamber" — water chamber,
transducer ring(s), holographic torso with internal organ glows and
class-tinted contour slices, live HUD (acoustic paths, phantom fidelity,
path confidence, body composition), cranio-caudal scrubber. Driven entirely
by real reconstruction data.
Docs (docs/sonic-ct): 8 ADRs, SOTA research map, market brief, SPARC.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(sonic_ct ui): welcome modal + GLB body-model loader with procedural fallback
- WelcomeModal: Simulate/Reconstruct/Analyze/Validate intro, Get Started cards,
"show on startup" preference, research-only disclaimer.
- BodyModel: loads a supplied GLB anatomy model (GLB_URL) and applies a ghost
material override + per-organ tinting from organ_manifest.json; cleanly falls
back to the procedural violet ghost (torso + internal organ glows) when no
asset is supplied or it fails to load. GLB is a visual prior only — the Rust
phantom stays the physics ground truth.
- Refined holographic ghost: violet volumetric glow, class-tinted contour
slices, twin transducer rings, glowing base, internal organ volumes.
- docs/sonic-ct/BODY-MODELS.md: researched model sources (Zygote, BioDigital,
SMPL/Meshcapade, Z-Anatomy, BodyParts3D) + GLB integration pipeline.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(sonic_ct ui): load open-source CesiumMan GLB as the ghost body shell
- Ship CesiumMan (Khronos glTF Sample Assets, CC-BY 4.0) as public/models/human.glb,
loaded via useGLTF, auto-fit to the chamber, and styled with the ghost-material
override; procedural internal organ glows render inside it.
- GLB_URL now points at the bundled model; missing/broken asset still falls back
to the procedural torso shell via the error boundary.
- Attribution recorded in organ_manifest.json and docs/sonic-ct/BODY-MODELS.md.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(metabiohacker): organ-hypothesis detector, Darwin optimizer, rebrand
Rename the app to MetaBioHacker (Acoustic Digital Human Workbench · Sonic
Chamber) across HUD, welcome modal, and metadata.
Organ inference (ADR-0009/0010): new `crates/sonic-ct/src/organ.rs` detects
liver, spleen, kidneys, aorta, heart, and lungs from the reconstructed
volume using anatomical priors (zone, side, size, posterior adjacency,
slice-consistency) — never from speed alone. Each hypothesis carries a
confidence and an evidence bitmask. Exposed via WASM (sct_organ_*,
sct_quality_flag) and surfaced in a new HUD panel with per-organ confidence
bars + quality flags (bone shadowing / sparse coverage / boundary
uncertainty / gas). 18 Rust tests pass; clippy clean.
Harness optimization (examples/sonic-ct/optimize.mjs): uses
@metaharness/darwin ("freeze the model, evolve the harness") with
cheap->frontier tiering and Pareto selection over the frozen WASM engine to
evolve {elements, fan, iters}; lifts phantom fidelity ~0.53 -> ~0.59.
Documented in docs/sonic-ct/OPTIMIZATION.md.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(metabiohacker): faithful Darwin harness evolution + OpenRouter write layer
- crates/sonic-ct/src/bin/serve.rs: the frozen acoustic engine as a JSON-over-
stdio process (sonic_ct_serve) — the physics truth layer for the evolver.
- examples/sonic-ct/src/optimizer/reconstructionEvolution.ts: typed genome
(reconstruction/routing/scoring/safety), runFrozenRustEngine (spawns the real
binary), cheap->frontier routeReconstruction (augments engine output, never
rewrites anatomy), multi-objective scoreCandidate, mutateGenome, and
evolveMetaBioHarness using Darwin mapLimit + paretoFront + an archive.
- optimize.mjs: OpenRouter LLM "write layer" proposes harness mutations (cheap
gpt-4o-mini / frontier gpt-4o), gated by routing policy, bounded budget, key
read from env only; archive-based acceptance gate now PASSES (latency -92.8%,
no regression). probeDarwin.mjs verifies the export surface.
- Tests (npm test, Node type-stripping): mapLimit bounds concurrency; paretoFront
keeps accurate+cheap trade-offs and drops dominated; frontier never bypasses
the frozen engine. docs/sonic-ct/OPTIMIZATION.md updated.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* docs(metabiohacker): ADRs 0009-0019 — organ inference, harness evolution, multimodal data + governance
Add 11 ADRs and an index covering the layers built and the medical-data
architecture roadmap:
Organ/inference layer (grounded in organ.rs / segmentation.rs / Hud.jsx):
- 0009 five acoustic classes canonical (no organ identity from speed alone)
- 0010 organ identity inferred from anatomical priors (evidence + confidence)
- 0011 organ function requires dynamic/multiparametric channels ("not measured")
- 0012 explainability mandatory (evidence bitmask surfaced in the UI)
- 0013 no disease labels — research mode only
Harness + data architecture:
- 0014 freeze the physics engine, evolve the reconstruction harness (Darwin)
- 0015 patient data as a graph of typed observations (MedicalObservation,
provenance + uncertainty + consent scope)
- 0016 adopt DICOM / FHIR / LOINC / SNOMED CT / OMOP + RuVector similarity index
- 0017 typed multimodal fusion patterns (monitoring/research, not diagnosis)
- 0018 governance & SaMD boundary (FDA GMLP/PCCP, Health Canada, Ontario PHIPA)
- 0019 a medical signal operating system, not an AI doctor
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(metabiohacker): benchmark harness on real CT data + synthetic corpus
- Real-data ingestion: Grid::from_pgm (P5 parser), Phantom::from_intensity_grid
(band a grayscale CT slice into the five acoustic classes), and
pipeline::run_with_phantom (reconstruct a supplied phantom — engine unchanged).
- sonic_ct_serve gains a phantomPgm path: reconstruct a real anatomical slice
instead of a procedural one and emit the same score schema.
- tools/fetchRealSlice.mjs: fetch a public-domain abdominal CT slice (Wikimedia
Commons) and convert to a grayscale PGM (image not committed; fetched on
demand, derived PGM gitignored).
- benchmark.mjs (npm run benchmark): baseline vs Darwin-evolved harness over 12
reproducible synthetic phantoms + 1 real CT slice; writes docs/sonic-ct/
BENCHMARK.md + benchmark.report.json. Representative: evolved harness ~157%
faster at equal Dice; real CT honestly harder (Dice ~0.27).
- New integration test exercises the PGM/real-phantom reconstruction path
(19 Rust tests pass).
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(metabiohacker): scale benchmark — 40 synthetic seeds + multiple real CT slices, 95% CI
- fetchRealSlice.mjs fetches several public-domain CT slices (abdomen, thorax,
pelvis) resiliently, skipping unavailable ones.
- benchmark.mjs now runs N synthetic seeds (default 40) + every fetched real
slice, reports mean ± 95% CI, and writes docs/sonic-ct/BENCHMARK.md.
Representative: 42 samples, evolved harness ~149% faster at equal Dice
(±0.002 CI); real CT slices honestly harder (Dice ~0.30).
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(metabiohacker): Multimodal Ingest V0 — observations, graph, fusion, ledger, ruvn evidence gate
New package packages/metabiohacker (@metabiohacker/core, TS, 14 tests pass):
- ingest/: canonical MedicalObservation + lab (CSV→LOINC), imaging (DICOM
sidecar), and pathology adapters with provenance/uncertainty/consent.
- graph/: auditable patient state graph + rule-based contradiction detection
(low-quality, ≥2x same-test disagreement, unflagged review modalities).
- fusion/: prior builder (data shapes priors, never forces conclusions),
multimodal scoring (acoustic residual passed through unchanged), contradiction
penalty, and a Darwin harness (mapLimit + paretoFront) selecting fusion policy.
- evidence/: ruvn as the evidence-intelligence layer (off the hot path) — provider
interface, A/B-or-blocked claim gate, deterministic cached provider + optional
@ruvnet/ruvn CLI adapter (never a hard dep). Claims ship only on grade A/B with
citations; pathology/biopsy/Pap/HPV/cytology force human review.
- ledger/ + output/: stable-hash reconstruction run ledger (tamper-evident,
verifiable) and the safe UI packet (uncertainty overlay, diagnosis blocked).
Benchmark: +10% stability, ~37% uncertainty drop, residual unchanged, ledger
verified, clinical-review mode forced by pathology.
Docs: ADR-0020 (canonical observation), 0021 (graph+contradictions),
0022 (run ledger), 0023 (ruvn evidence layer); ADR index updated.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(metabiohacker): real-slice calibration, domain-gap honesty gate, evidence refresh, CI gates
Attacks the synthetic→real Dice gap honestly rather than hiding it.
- Engine: sonic_ct_serve emits per-class (region) Dice on real slices.
- calibration/: region-level Dice (diceByRegion), domain-gap scoring +
honesty gate (classifyRealSliceResult: headline/researchOnly/exclude),
centroid registration-error + boundary-complexity proxies. Real CT slices are
calibration targets, not USCT.
- benchmark.mjs: 3-section report (synthetic / real region-level / governance);
headline separates speed from real fidelity. Real slices now classify as
exclude/researchOnly and stay out of headline metrics (abdomen~0.30).
- evidence:refresh (OpenRouter): grades modality evidence into docs/evidence/*.md
+ a candidate cache; promotion to the curated cache stays a reviewed step.
Live run graded acoustic USCT = C (research-only), MRI = B.
- CI gates (ciGates.test.ts + .github/workflows/metabiohacker-ci.yml): residual
invariant, pathology review forced, A/B-only claims, real-slice honesty gate.
23 metabiohacker tests + 12 Rust integration tests pass. ADR-0024 added.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(sonic_ct): method comparison vs BP/SART/Landweber on Shepp-Logan with RMSE/PSNR/SSIM
Bench reconstruction against recognised algorithms on a recognised target:
- shepp_logan.rs: standard 10-ellipse Shepp-Logan phantom -> speed map.
- reconstruction.rs: Method enum + reconstruct_speed_with; Landweber solver
(gradient descent on ‖As−t‖²) alongside backprojection (1 sweep) and SART.
- metrics.rs: standard image-quality metrics RMSE, PSNR (dB), SSIM.
- sonic_ct_methods bin -> docs/sonic-ct/METHOD-BENCHMARK.md (deterministic).
Measured: backprojection < SART < Landweber on every metric for both Shepp-Logan
and abdomen (abdomen RMSE 130→99→51 m/s, SSIM 0.22→0.60→0.92) at ~4/28/100 ms.
SART stays production default; Landweber is the higher-fidelity option. 2 new
tests; 14 integration tests pass; clippy clean. ADR-0025 added.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(metabiohacker): rigid translation registration for real-slice calibration
Replace the centroid-only proxy with registerByTranslation — finds the integer
offset that maximises predicted/target body-mask overlap Dice, returning the
offset, residual misalignment (errorPx), and aligned overlap. Gives the
domain-gap honesty gate a real registration estimate (landmark refinement is the
next step). +1 test (recovers a known offset; maximises overlap). 24 tests pass.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(sonic_ct): full-waveform inversion (FWI) — forward + adjoint-state gradient
The SOTA step beyond straight-ray TOF (ADR-0004 roadmap), as a dependency-free
2-D reference:
- fwi.rs: FDTD scalar-wave forward model (∂ₜ²p = κ∇²p + f), CFL-stable, damping
sponge; adjoint-state gradient ∂χ/∂κ = Σ_t λ ∇²p; gradient descent with
source/receiver-footprint muting, smoothing, and backtracking line search.
- Proven by the gold-standard adjoint-vs-finite-difference gradient check
(cosine > 0.85) + an inversion that cuts data misfit ≥15% and recovers a
centrally-concentrated velocity anomaly. 2 new tests; 23 Rust tests pass;
clippy clean.
- Honest scope: single-frequency, unregularised — frequency continuation,
regularisation, source encoding, and 3-D are the documented next steps; no
quantitative clinical recovery claimed. ADR-0026 added.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
* feat(sonic-ct): add FWI frequency continuation (multiscale inversion)
Add invert_multiscale + Stage to fwi.rs: chains low->high frequency FWI
stages with between-stage model smoothing to avoid cycle-skipping. Low
frequencies recover the smooth background first, keeping high-frequency
stages out of local minima.
Proven by a third FWI test: frequency continuation lowers the
inclusion-region error below single-scale FWI at matched iteration count
(deterministic). Adjoint-vs-FD gradient check and misfit-reduction tests
still pass. Updates ADR-0026.
Co-Authored-By: claude-flow <ruv@ruv.net>
Claude-Session: https://claude.ai/code/session_01Mx4vKMfvsq5KBQgPRSoxM7
---------
Co-authored-by: Claude <noreply@anthropic.com>
Product Quantization (PQ) with Asymmetric Distance Computation (ADC)
fills the gap between RaBitQ (1-bit, 15×) and raw f32 storage.
M=8, K=256 achieves 64× compression at 78 KB for 10K×128 vectors.
Covers three variants: FlatPQ (2127 QPS, recall@10=0.253),
IVF+PQ (13471 QPS, recall@10=0.210), ResidualPQ (1740 QPS,
recall@10=0.678). All numbers measured via cargo run --release.
Claude-Session: https://claude.ai/code/session_01AJnxEruiS1c2kYe8wAPFMv
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: ruvnet <ruvnet@gmail.com>
