Expand description
The engine: typed capabilities over a workspace and a language registry.
Engine::run dispatches a Request and returns an in-process Execution.
Queries answer with concrete data; mutations retain Planned results until
Apply writes and commits their history entry. Intent is the
mutation description shared by history and batch.
Typed clients call capability-owned execute, plan, or apply methods,
and Ledger owns history and undo. The dispatcher orchestrates those bodies;
interfaces consume Execution::into_answer only at a reporting boundary.
Mutation capability types have one canonical public path, at the crate root:
use vvv_engine::{Rename, RenameIntent, Move, MoveIntent, MoveSymbol, MoveSymbolIntent};
let _: Option<(Rename, RenameIntent, Move, MoveIntent, MoveSymbol, MoveSymbolIntent)> = None;They are not aliases in protocol:
ⓘ
use vvv_engine::protocol::{Rename, RenameIntent, Move, MoveIntent, MoveSymbol, MoveSymbolIntent};Their owning capability modules are private:
ⓘ
use vvv_engine::capabilities::rename::Rename;Re-exports§
pub use protocol::Answer;pub use protocol::Batch;pub use protocol::BatchIntent;pub use protocol::Call;pub use protocol::Confidence;pub use protocol::Consumer;pub use protocol::Dead;pub use protocol::DeadQuery;pub use protocol::Definitions;pub use protocol::Dep;pub use protocol::Deps;pub use protocol::DepsQuery;pub use protocol::ErrorCode;pub use protocol::ExplainQuery;pub use protocol::Explanation;pub use protocol::Exposed;pub use protocol::Failure;pub use protocol::File;pub use protocol::FileChange;pub use protocol::FileQuery;pub use protocol::History;pub use protocol::HistoryEntry;pub use protocol::Impact;pub use protocol::ImpactQuery;pub use protocol::ImportSite;pub use protocol::Importer;pub use protocol::ImportsQuery;pub use protocol::ImportsReport;pub use protocol::Intent;pub use protocol::Locations;pub use protocol::Match;pub use protocol::MatchId;pub use protocol::Mutation;pub use protocol::MutationAnswer;pub use protocol::MutationState;pub use protocol::Notice;pub use protocol::NoticeKind;pub use protocol::Occurrence;pub use protocol::Outline;pub use protocol::OutlineItem;pub use protocol::OutlineQuery;pub use protocol::Placed;pub use protocol::Reach;pub use protocol::Reason;pub use protocol::Recovery;pub use protocol::RecoveryEffect;pub use protocol::RecoveryIssue;pub use protocol::RecoveryOperation;pub use protocol::RecoveryState;pub use protocol::RecoveryUnverified;pub use protocol::References;pub use protocol::ReferencesQuery;pub use protocol::Reply;pub use protocol::Request;pub use protocol::Respelling;pub use protocol::Rewrite;pub use protocol::RewriteIntent;pub use protocol::RewriteOf;pub use protocol::Search;pub use protocol::SearchQuery;pub use protocol::SearchScope;pub use protocol::Selection;pub use protocol::SelectionError;pub use protocol::Site;pub use protocol::Skipped;pub use protocol::Surface;pub use protocol::SurfaceQuery;pub use protocol::Template;pub use protocol::TemplateError;pub use protocol::Undo;pub use protocol::Unreferenced;pub use protocol::WhereQuery;pub use protocol::WorkspaceFiles;pub use protocol::WorkspaceFilesQuery;pub use protocol::ContentId;pub use protocol::DefinitionCandidate;pub use protocol::DefinitionPreview;pub use protocol::ResolutionEvidence;pub use protocol::SnapshotId;pub use protocol::SourceAnchor;pub use protocol::SymbolRef;pub use protocol::ContextBudget;pub use protocol::ContextCandidate;pub use protocol::ContextDetail;pub use protocol::ContextItem;pub use protocol::ContextOmissions;pub use protocol::ContextOutcome;pub use protocol::ContextQuery;pub use protocol::ContextRelation;pub use protocol::ContextReply;pub use protocol::ContextSignature;pub use protocol::Capability;pub use protocol::Discovery;pub use protocol::DiscoveryQuery;pub use protocol::OutputLimit;pub use protocol::Command;pub use protocol::ContextPage;pub use protocol::ContextPageQuery;pub use protocol::ContextUnresolved;pub use protocol::ContextWork;pub use protocol::ContinuationRecovery;pub use protocol::ContinueQuery;pub use protocol::Cursor;pub use protocol::ExpandQuery;pub use protocol::Expansion;pub use protocol::PageBudget;pub use protocol::PageReply;pub use protocol::PagedContextItem;pub use protocol::QueryLimits;pub use protocol::SearchPage;pub use protocol::SearchPageItem;pub use protocol::SearchPageQuery;pub use protocol::WorkBudget;pub use protocol::DefinitionLocation;pub use protocol::ResolutionOutcome;pub use protocol::ResolutionQuery;pub use protocol::ResolutionReply;pub use protocol::ApplyPlanQuery;pub use protocol::DiscardPlanQuery;pub use protocol::InspectPlanQuery;pub use protocol::PlanId;pub use protocol::PlanPreview;pub use protocol::PlanReceipt;pub use protocol::PlanReview;pub use protocol::PlanReviewCursor;pub use protocol::PlanReviewItem;pub use protocol::PlanReviewKind;pub use protocol::PlanReviewPage;pub use protocol::PlanReviewReply;pub use protocol::PlanStatus;pub use protocol::PrepareMoveIntent;pub use protocol::PrepareMoveQuery;pub use protocol::PrepareMoveSymbolIntent;pub use protocol::PrepareMoveSymbolQuery;pub use protocol::PrepareRenameQuery;pub use protocol::PrepareRewriteQuery;pub use protocol::ReviewMutation;pub use protocol::ReviewPlanQuery;pub use protocol::ReviewSection;pub use protocol::ReviewTotals;
Modules§
- protocol
- The JSON contract. Anything printed by
vvv --jsonis one of these types, so a client can rely on the shape independently of the CLI’s human output. - report
- Shared report vocabulary. Capabilities compose answers into
Documents; aViewlays those facts out as rows. Composition stays onDocument, implemented beside each capability’s execution. No report is serialized.
Structs§
- Address
- The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
A position in a language’s namespace: the package it belongs to and the
path within it —
fff :: [grep, types]for a Rust module, path components for a TypeScript file. Prefix relations, which are what a move cares about, never hold across packages. - Applied
- A successful apply with the required id of its committed history entry. Construction is private and result access is immutable.
- Apply
- Write what was planned and record it as one history entry — one undo. A batch’s steps go in order, each checked against the state the previous one left; if a step fails, the ones before it are rolled back. Answers with the result marked applied. Query answers cannot be applied:
- Check
Command - Check
Failure - Check
Output - Check
Result - DiskVfs
- Real file system. Walks respect
.gitignoreand skip hidden entries. - Edit
- The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
Replace the bytes at
spanwithreplacement. - Engine
- File
Preview - Highlight
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
- Import
Group - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Where a grouped entry sits, so a surgery can rewrite it in place or move it out of the group.
- Import
Ref - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
One path in one file.
spancovers exactly the text a rewrite replaces. - Language
Id - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
Stable identifier of a language (
rust,typescript, …). - Languages
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. The set of languages an engine knows about. Filled at startup; read-only after.
- Ledger
- Memory
Vfs - In-memory file tree. Paths are stored exactly as given. Every write and rename gives the file a fresh version, so stamps behave like mtimes.
- Modifier
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A visibility modifier as it appears in the source.
- Module
Path - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A path as spelled in source: its head and its segments, with the syntax that spells it. Serialises as the text, so the wire is what the user wrote.
- Move
vvv move: a file or directory moved, its importers respelled.- Move
Error - Move
Intent - Move a file and make every reference to it follow.
- Move
Symbol vvv move --symbol: one declaration moved between files.- Move
Symbol Intent - Move one declaration — with what belongs to it in the text, and for Rust
its
implblocks — from the file declaring it to another file of the same language, and make every reference follow. - Name
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. One identifier: a module, a declaration, a file stem. Compared by text.
- Navigation
Cancellation - Package
Id - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
The name a package goes by in paths: a Rust crate’s lib name (
fff, notfff-search), a TypeScript package’s name. The layout decides the spelling. - Parent
Creation - Parent directories created before a file mutation, including partial failure.
- Plan
Limits - Planned
- What a mutating command returns: the result as a preview —
appliedis false,filesshows what would change — and, kept beside it, the plan(s)Applywrites. The plan never leaves the process. Session plan handles reference it without accepting executable edits back from a client; an ordinary serialized mutation result has no apply handle. Queries cannot carry executable plans: - Position
- The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
Zero-based line and character column. Columns count
chars, not bytes, so they are safe to show to humans and editors. - Provider
Version - Query
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
- Query
Builder - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
Assemble a
Queryfrom optional parts (typically CLI flags). - Read
Cancellation - A single-use cancellation handle for reads and explicit validation. Clones cancel the same call. Cancellation stops at the next engine checkpoint, not within a parser invocation.
- Recovery
Error - A failed mutation whose effects could not all be restored and verified.
- Referent
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Where a declaration is: the file and the span of its name, both as the workspace spells them (relative paths).
- RelPath
- The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
A file’s path inside the workspace, spelled the way the project does:
/on every platform. - Relationship
- Relationship
Budget - Relationship
Coverage - Relationships
- Relationships
Query - Rename
vvv rename: the declaration and every occurrence, each judged.- Rename
Intent - Rename the declaration(s) called
nameand every identifier that spells it. - Semantic
Reply - Semantic
Request - Source
Version - Span
- The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
Half-open byte range
[start, end)inside a single file. - Stamp
- A cheap witness of a file’s state: modification time and size on disk, a
version counter in memory. Two equal stamps mean the contents could not
have changed, which is what lets a warm corpus skip the read. Like
makeandgit, it trusts the clock: an edit that keeps the length and lands within the same timestamp tick is invisible until the next one. Writes are never trusted to a stamp —Plan::applychecks content fingerprints. - Symbol
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. A declaration found in one file.
- Symbol
Move Candidate - Symbol
Move Candidates - Symbol
Move Candidates Query - Symbol
Move Piece - Validate
Plan Query - Validation
Budget - Validation
Report - Workspace
Enums§
- Apply
Error - Call
Kind - Capture
Value - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
$Abinds one node;$$$Abinds a sequence. - Check
Operation - Check
Outcome - Engine
Error - Entry
Kind - Execution
- An in-process result. Only mutation previews carry executable plans.
- Execution
Kind - The kind of retained result requested by an in-process caller.
- Extraction
Error - Invalid declaration extents or edits in the text selected for a move.
- Highlight
Kind - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. The classes a display distinguishes. Coarse on purpose: enough to read code, not enough to argue about.
- History
Error - Move
State - The file effects of a failed move. Unknown outcomes require observation.
- Path
Head - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. Where a path starts: the part before its segments that says what they are relative to.
- Path
Syntax - The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
How a language spells paths: the separator between segments and the
words it uses for a head. A grammar declares one; it parses import text
into
ModulePaths and spells them back. - Query
Error - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate.
- Reach
Kind - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. What a visibility modifier means, relative to the declaring module.
- Relationship
Kind - Relationship
Limit - Relationship
Limitation - Relationship
Resolution - Retention
- How long an
Enginekeeps its graph. - Role
- The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. What position a match occupies in its file: the declaration itself, a token inside an import statement, or any other use. Views lead with declarations and dim imports; the engine orders results by it.
- Semantic
Failure - Semantic
Target - Symbol
Kind - The nouns of the plugin contract that appear in the engine’s answers, so an interface needs nothing but this crate. What a declaration declares, in vocabulary shared by every language.
- Symbol
Move Ownership - Symbol
Move Unsupported - Validation
Source State - VfsError
Traits§
- Navigation
Provider - A provider revision must change whenever any semantic input changes, including build options and external dependencies. Providers must be bounded, cooperate with cancellation, and must not re-enter this engine while answering.
- Oracle
- The nouns of the plugin contract that appear in the engine’s answers, so
an interface needs nothing but this crate.
Something that can say what an identifier refers to. Asked one token at
a time, only for tokens the graph could not judge, and never trusted
blindly: the engine maps the answer onto a declaration it knows before
it counts. Implementations are free to answer
Nonefor anything. - Vfs