Virtual Raindex live facade#2181
Open
hardyjosh wants to merge 4 commits into2025-10-03-vr-live-quotefrom
Open
Conversation
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughAdds a new virtual-raindex crate with engine, state, types, error surface, REVM-backed interpreter host, event ingestion, live sync facade with adapters and status model, cache implementation, snapshots, and extensive tests plus docs. Updates test fixtures to robustly spawn Anvil. Introduces crate manifest and READMEs. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant LVR as LiveVirtualRaindex
participant SE as SyncEngine
participant CC as CodeCache
participant SS as SnapshotStore
participant CS as CursorStore
User->>LVR: sync_once()
LVR->>CS: load_cursor(orderbook)
LVR->>SE: poll(orderbook, cursor?)
SE-->>LVR: SyncPoll{bytecode, mutation_batches, next_cursor, pending, heartbeat}
loop Ingest artifacts
LVR->>CC: ingest(BytecodeArtifact)
CC-->>LVR: Result
end
alt Batches ready
LVR->>LVR: apply ready MutationEnvelope(s)
else Pending artifacts
LVR->>LVR: enqueue pending envelopes (warmup queue)
end
opt Next cursor
LVR->>CS: persist_cursor(orderbook, next_cursor)
end
opt Snapshot change
LVR->>SS: persist_snapshot(SnapshotBundle)
end
LVR-->>User: LiveStatus (Idle|Syncing|PendingArtifacts|Errored)
sequenceDiagram
autonumber
actor Caller
participant VR as VirtualRaindex
participant CC as CodeCache
participant IH as InterpreterHost
Caller->>VR: quote(QuoteRequest)
VR->>CC: ensure_artifacts(order)
VR->>VR: build context + store snapshot
VR->>IH: eval4(interpreter, EvalV4, snapshot, env)
IH-->>VR: EvalOutcome{stack,writes}
VR-->>Caller: Quote{io_ratio, output_max, stack, writes}
Estimated code review effort🎯 5 (Critical) | ⏱️ ~120 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Pre-merge checks and finishing touches and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
Comment |
hardyjosh
changed the base branch from
2025-10-01-vr-event-stream
to
2025-10-03-vr-live-quote
rouzwelt
requested changes
Oct 9, 2025
| offline resumes cheap. | ||
|
|
||
| ## Bytecode Warmup Strategy | ||
| - Sync engines may stream `MutationEnvelope`s before matching bytecode is ready. The façade determines the |
| - `live::SyncEngine` – host-supplied async trait that yields mutation envelopes, hydrated bytecode, and | ||
| currently fetching artifacts. The stub implementation lives in `live::stub` and is backed by deterministic | ||
| scripts. | ||
| - `live::LiveVirtualRaindex` – façade owning the engine, code cache, interpreter host, and persistence |
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.
Caution
This PR is chained to #2176, review and merge
Motivation
#2176 made the virtual engine snapshot-friendly and wasm-ready, but callers still had to orchestrate their own live syncing, bytecode hydration, and persistence. Every consumer (RaindexClient, solvers etc) would otherwise rebuild the same scaffolding—polling for mutations, retrying while bytecode warms up, storing snapshots/cursors, and surfacing “warming up” telemetry. We needed a reusable façade so hosts can keep a VirtualRaindex instance live without re-implementing that plumbing, and we needed deterministic fixtures to exercise the flow before the local DB pipeline lands.
Solution
livemodule exportingLiveVirtualRaindex, which owns the engine, mutation queue, and bytecode warm-up. The builder takes pluggable adapters (SnapshotStore,CursorStore,MetricsSink) so hosts can supply their own storage and telemetry.SyncEnginetrait plus supporting types (MutationEnvelope,SyncPoll,BytecodeArtifact) so hosts can stream mutations, cached bytecode, and pending artifacts into the façade.StubSyncEngine+ JSON fixtures for deterministic tests and examples.LiveCodeCacheso the façade ingests artifacts asynchronously, retries deferred mutations, and emitsLiveStatusadvisories (Idle,Syncing,PendingArtifacts,Errored).src/live/README.md, and highlight the live sync entry point in the crate README.Checks
By submitting this for review, I'm confirming I've done the following:
Summary by CodeRabbit
New Features
Documentation
Tests
Chores