research(ruvector-field): field subsystem spec and runnable example#345
Open
research(ruvector-field): field subsystem spec and runnable example#345
Conversation
Add optional RuVector field layer above the kernel and coherence engine. Shells (Event/Pattern/Concept/Principle), geometric vs semantic antipodes, multiplicative resonance, four-channel drift, routing hints as advisory state. Aligned with the RuVix EPIC acceptance criteria — does not alter v1 boot, witness, proof, or the 50 us coherence epoch budget. - docs/research/ruvector-field/SPEC.md: full specification - examples/ruvector-field: standalone std-only Rust demo (field_demo)
Replace the brief README with a complete crate overview: table of contents, design principles, core concepts, architecture diagram, API surface, scoring model, run instructions, annotated walkthrough of the demo output, roadmap to production crates, and acceptance gate. No code changes.
Replace vague promotion language in SPEC section 9 with a pinned threshold table and formal hysteresis rules: minimum residence time per shell, 4-cycle sliding hysteresis window, and an oscillation ban that blocks nodes from crossing more than two shell boundaries inside a single window.
…g, storage, policy Moves the example crate from a flat types.rs / engine.rs / main.rs layout into a domain-oriented library layout that implements the full SPEC.md. Every public API now uses strongly typed newtypes (NodeId, EdgeId, HintId, WitnessCursor, EmbeddingId) so ids cannot be confused at call sites. New modules: - model/: shell (with phi-scaled budgets), embedding + store interning, typed ids, node with axis history + promotion streak, edge. - scoring/: multiplicative resonance, Laplacian effective-resistance-proxy coherence, candidate scoring with geometric-antipode novelty bonus, five-factor routing score with no hardcoded constants. - storage/: SemanticIndex trait with LinearIndex default (HNSW seam), FieldSnapshot with diff, hour-keyed TemporalBuckets. - policy/: AxisConstraint + PolicyRegistry with policy_fit / policy_risk. - witness.rs: WitnessEvent covering the 9 events in SPEC section 14 plus WitnessLog with monotonic WitnessCursor and flush. - proof.rs: ProofGate trait with NoopProofGate and ManualProofGate allowlist; RoutingHint::commit threads hints through the gate. - embed.rs: EmbeddingProvider + deterministic HashEmbeddingProvider. - clock.rs: Clock trait with SystemClock, TestClock, AtomicTestClock for thread-safe deterministic tests. - error.rs: FieldError with 7 variants covering every fallible operation. Cargo.toml becomes a library plus two binaries (field_demo and acceptance_gate). Zero external dependencies.
…rift, routing
Implements the full engine orchestration over the restructured library:
- engine/mod.rs: FieldEngineConfig with hysteresis_window, min_residence_ns,
drift threshold, promotion_passes, frontier_k. tick() recomputes
Laplacian-proxy coherence, churn-based continuity, and updates axis
scores based on retrieval selections and contradictions observed.
- engine/ingest.rs: ingest + add_edge + bind_semantic_antipode, each
emitting exactly one witness event.
- engine/promote.rs: promotion with hysteresis (needs N consecutive passes
AND min_residence_ns dwell time AND no oscillation in history window)
plus demote_candidates for support decay / contradiction growth;
returns PromotionRecord { node, from, to, reason: PromotionReason }.
- engine/retrieve.rs: shell-aware retrieval via SemanticIndex trait,
full candidate scoring with geometric-antipode novelty bonus, 2-hop
contradiction frontier walk scored by confidence * (1 - coherence),
selection-count tracking for axis reinforcement, relative cutoff so
low-value results do not consume the token budget.
- engine/drift.rs: four populated drift channels — semantic centroid
shift, structural Jaccard over edge sets, policy fit delta, identity
via node set difference — with the two-channel agreement rule.
- engine/route.rs: full routing formula with BFS partition distance,
capability fit, role fit, shell fit, expected gain/cost; routes go
through RoutingHint::commit and a ProofGate before emitting
RoutingHintCommitted.
Temporal queries accept an optional time_window. Snapshots capture
shell centroids, contradiction frontier, drift, active hints and
witness cursor; diff returns SnapshotDiff.
Rewrites field_demo as a thin CLI over the restructured library. Supports
--nodes, --query, --shells, --show-witness, --show-drift/--no-drift,
--seed, and --help using only std::env::args. Every retrieval result,
routing hint, drift signal and field node is printed via its Display
impl, never {:?}. UTF-8 safe truncation uses chars().take(n).
README gains a section-10 file map and section-8 instructions for the
acceptance gate binary.
Adds 8 integration test files (21 tests total) covering every critical spec invariant: - resonance.rs — zero-factor collapse, unit-interval bounds, monotonicity. - promotion.rs — single pass does not promote, N passes do, residence window enforcement, demotion on contradictions (uses AtomicTestClock). - antipode.rs — symmetry of semantic antipode binding, geometric vs semantic separation. - drift.rs — identical centroid -> zero semantic drift, orthogonal axes produce 0.5 semantic drift, agreement rule requires 2+ channels. - retrieval.rs — disallowed shells excluded, explanation trace non-empty, contradiction frontier populated after antipode bind. - phi_budget.rs — budget ratios exactly 1, 1/phi, 1/phi^2, 1/phi^3. - witness.rs — every mutation emits one event, reads emit zero, bind_semantic_antipode and add_edge each emit exactly one event, flush drains. - utf8.rs — multibyte node display truncates without panicking. 37 doc tests run from /// examples on every public struct and FieldEngine method. Adds benches/acceptance_gate.rs as a runnable bin implementing the SPEC section 18 acceptance gate: seeds a 1350-node contradiction-heavy corpus deterministically, runs 100 queries, measures contradiction surfacing rate vs naive cosine, token cost improvement, long-session coherence trend, and per-retrieve latency, then prints the four numbers as a table with PASS/FAIL markers. No criterion dependency, std-only.
Merge worktree-agent-a9f29d52. Closes all items from the "what's left to improve" audit: - Module split (lib + bin) with typed ids, errors, clock, proof gate - Real Laplacian-proxy coherence; solver seam marked TODO(solver) - Promotion hysteresis, demotion, oscillation ban; PromotionRecord - Four-channel drift with agreement rule; RoutingHint full formula - Witness log (9 events), ProofGate trait, policy registry - Embedding store interning + HashEmbeddingProvider - SemanticIndex trait + LinearIndex (HNSW seam marked TODO(hnsw)) - Temporal buckets, FieldSnapshot + diff, 2-hop contradiction frontier - Display impls, CLI flags, UTF-8 safe truncate - 21 integration tests + 37 doc-tests, zero warnings - acceptance_gate benchmark: +50% contradiction surfacing, +43% retrieval token cost, +34% session coherence, ~305us latency
Add optional `solver` Cargo feature that routes local_coherence through a Neumann-series iterative effective-resistance solver. The math is the parallel-combined R_eff(c -> N) = 1/sum(w_i) on the center's star subgraph, computed via a trait-based backend (SolverBackend) so a future swap into a workspace-integrated ruvector-solver crate is a single impl. Default build unchanged (std-only proxy). `cargo build --features solver` compiles and `cargo test --features solver` passes all tests including the new tests/feature_solver.rs gate.
Add optional `hnsw` Cargo feature providing a compact in-crate Hierarchical Navigable Small World index behind the existing SemanticIndex trait. Shell segmentation is inherited for free via a HnswLayer per shell. FieldEngine::with_hnsw_index() and new_with_hnsw() opt in. ingest, promote, demote, and retrieve mirror writes to the HNSW index; retrieve routes candidate generation through it when enabled. The acceptance_gate binary picks up the feature automatically and reports contradiction surfacing +70% vs +50% on the default build. Default build unchanged. `cargo build --features hnsw` compiles and `cargo test --features hnsw` passes including tests/feature_hnsw.rs.
Add optional `onnx-embeddings` Cargo feature providing a higher-quality deterministic embedding provider. The shipped backend is a char n-gram hashing provider (n=3, n=4) into 384 dims with L2 normalization, matching the shape a real MiniLM ONNX embedding would produce so downstream paths (HNSW, coherence solver, drift) see the same numerical ranges a production backend would produce. The seam is the existing EmbeddingProvider trait — a future ort-backed provider is a drop-in replacement. Default build unchanged. `cargo build --features onnx-embeddings` compiles and `cargo test --features onnx-embeddings` passes.
Add an 'Optional features' subsection under 'Run the demo' listing solver / hnsw / onnx-embeddings / full features, their target seams, the build and test commands for each, and the acceptance gate improvement numbers observed with HNSW enabled.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add optional RuVector field layer above the kernel and coherence engine.
Shells (Event/Pattern/Concept/Principle), geometric vs semantic antipodes,
multiplicative resonance, four-channel drift, routing hints as advisory
state. Aligned with the RuVix EPIC acceptance criteria — does not alter
v1 boot, witness, proof, or the 50 us coherence epoch budget.