Skip to content

vox-orchestrator-queue API Reference (generated)

Crate: vox-orchestrator-queue · Version: 0.6.0 · Target: Library (lib.rs)

Locks, oplog, and affinity tracking for vox-orchestrator. Extracted in 2026-05-08 reorg Phase 5.

Queue/lock/oplog primitives for vox-orchestrator.

Extracted from vox-orchestrator (2026-05-08). Depends only on vox-orchestrator-types so it lives below the orchestrator core in the layer model.

DependencyKind
vox-configNormal
vox-cryptoNormal
vox-dbNormal
vox-orchestrator-typesNormal
ModuleDescription
affinity—
locks—
oplog—
projection—
projections—
sync_lock—
Dependency Topology, diagram 17 nodes, 6 edges: vox-orchestrator-queue → vox-config; vox-orchestrator-queue → vox-crypto; vox-orchestrator-queue → vox-db; vox-orchestrator-queue → vox-orchestrator-types; vox-orchestrator → vox-orchestrator-queue; vox-populi → vox-orchestrator-queuevox-orchestrator-queuevox-configvox-cryptovox-dbvox-orchestrator-typesvox-orchestratorvox-populi
Diagram source
graph {
direction: right
node vox_orchestrator_queue: "vox-orchestrator-queue"
node vox_config: "vox-config"
vox_orchestrator_queue -> vox_config
node vox_crypto: "vox-crypto"
vox_orchestrator_queue -> vox_crypto
node vox_db: "vox-db"
vox_orchestrator_queue -> vox_db
node vox_orchestrator_types: "vox-orchestrator-types"
vox_orchestrator_queue -> vox_orchestrator_types
node vox_orchestrator: "vox-orchestrator"
vox_orchestrator -> vox_orchestrator_queue
node vox_populi: "vox-populi"
vox_populi -> vox_orchestrator_queue
}
Consumer CrateRole
vox-orchestratorDirect workspace dependent
vox-populiDirect workspace dependent
KindSymbolSignatureSourceDescription
structaffinity::DaemonIdpub struct DaemonId(pub [u8; 16])crates/vox-orchestrator-queue/src/affinity.rs#L25Opaque identity of a daemon node (UUIDv4 bytes in network order).
structaffinity::Lamportpub struct Lamport(pub u64)crates/vox-orchestrator-queue/src/affinity.rs#L29Lamport logical clock value. Higher beats lower; ties broken by DaemonId bytes.
structaffinity::AffinityValuepub struct AffinityValuecrates/vox-orchestrator-queue/src/affinity.rs#L33-L39Value stored in the vector-clock affinity map (inner_v).
structaffinity::FileAffinityMappub struct FileAffinityMapcrates/vox-orchestrator-queue/src/affinity.rs#L52-L58Thread-safe map tracking which agent “owns” each file path. The single-writer principle: at most one agent holds write affinity for any given file. This prevents race conditions and lost updates. Affinity is a hint, lock is hard. See module-level docs.
fnaffinity::newpub fn new() -> Selfcrates/vox-orchestrator-queue/src/affinity.rs#L62-L68Create a new, empty affinity map.
fnaffinity::assign_vpub fn assign_v(crates/vox-orchestrator-queue/src/affinity.rs#L83Assign file affinity with Lamport LWW semantics and 60 s hold-down. Conflict resolution: 1. If the current owner is a different daemon and the entry is less than HOLD_DOWN_MS old, the new claim is ignored (local stability wins). 2. After the hold-down, the entry with the higher lamport wins; equal lamports break ties by daemon-id bytes (deterministic total order). Affinity is a hint, lock is hard. See module-level docs.
fnaffinity::lookup_vpub fn lookup_v(&self, file: &Path) -> Option<AffinityValue>crates/vox-orchestrator-queue/src/affinity.rs#L120-L122Look up the current vector-clock affinity owner for a file, if any. Affinity is a hint, lock is hard. See module-level docs.
fnaffinity::record_experiencepub fn record_experience(&self, agent: AgentId, file: &Path)crates/vox-orchestrator-queue/src/affinity.rs#L125-L140Record that an agent successfully worked on a file (dynamic learning).
fnaffinity::best_agent_forpub fn best_agent_for(&self, file: &Path) -> Option<AgentId>crates/vox-orchestrator-queue/src/affinity.rs#L143-L173Recommend the best agent for a file based on learned experience.
fnaffinity::assignpub fn assign(&self, file: &Path, agent: AgentId)crates/vox-orchestrator-queue/src/affinity.rs#L176-L178Assign a file to an agent. Overwrites any previous assignment.
fnaffinity::lookuppub fn lookup(&self, file: &Path) -> Option<AgentId>crates/vox-orchestrator-queue/src/affinity.rs#L181-L183Look up which agent owns a file, if any.
fnaffinity::releasepub fn release(&self, file: &Path)crates/vox-orchestrator-queue/src/affinity.rs#L186-L188Release ownership of a single file.
fnaffinity::release_allpub fn release_all(&self, agent: AgentId)crates/vox-orchestrator-queue/src/affinity.rs#L191-L193Release all files owned by the given agent.
fnaffinity::owner_or_assignpub fn owner_or_assign(&self, file: &Path, agent: AgentId) -> AgentIdcrates/vox-orchestrator-queue/src/affinity.rs#L197-L200Atomically look up the owner of a file, or assign it if unowned. Returns the actual owner (which may differ from agent if already claimed).
fnaffinity::files_for_agentpub fn files_for_agent(&self, agent: AgentId) -> Vec<PathBuf>crates/vox-orchestrator-queue/src/affinity.rs#L203-L209List all files owned by a given agent.
fnaffinity::agent_loadpub fn agent_load(&self) -> HashMap<AgentId, usize>crates/vox-orchestrator-queue/src/affinity.rs#L212-L219Return a map of agent → number of files owned (for load balancing).
fnaffinity::conflictspub fn conflicts(crates/vox-orchestrator-queue/src/affinity.rs#L223Check which files in a manifest are already owned by other agents. Returns (file_path, current_owner) pairs for each conflict.
fnaffinity::lenpub fn len(&self) -> usizecrates/vox-orchestrator-queue/src/affinity.rs#L244-L246Total number of file assignments.
fnaffinity::is_emptypub fn is_empty(&self) -> boolcrates/vox-orchestrator-queue/src/affinity.rs#L249-L251Whether the map is empty.
fnaffinity::as_jsonpub fn as_json(&self) -> serde_json::Valuecrates/vox-orchestrator-queue/src/affinity.rs#L254-L264Return the entire affinity map as a JSON object (Path -> AgentId).
enumlocks::LockKindpub enum LockKindcrates/vox-orchestrator-queue/src/locks/mod.rs#L20-L25Kind of lock an agent holds on a file.
structlocks::FileLockpub struct FileLockcrates/vox-orchestrator-queue/src/locks/mod.rs#L29-L38A file lock held by an agent.
enumlocks::LockConflictpub enum LockConflictcrates/vox-orchestrator-queue/src/locks/mod.rs#L42-L59Error returned when a lock cannot be acquired.
structlocks::FileLockManagerpub struct FileLockManagercrates/vox-orchestrator-queue/src/locks/mod.rs#L86-L95Thread-safe file-level lock manager. Enforces the single-writer principle: at most one agent can hold an exclusive lock on any file, while multiple agents can hold shared read locks. When constructed with [FileLockManager::with_db] the manager writes through to the vcs_lock table on every acquire/release so that a fresh daemon instance can replay the lock map on startup via [FileLockManager::hydrate_from_db].
structoplog::OperationIdpub struct OperationId(pub u64)crates/vox-orchestrator-queue/src/oplog/mod.rs#L30Unique operation identifier.
structoplog::OperationIdGeneratorpub struct OperationIdGenerator(AtomicU64)crates/vox-orchestrator-queue/src/oplog/mod.rs#L40Thread-safe generator for [OperationId]s.
fnoplog::newpub fn new() -> Selfcrates/vox-orchestrator-queue/src/oplog/mod.rs#L44-L46Create a new generator starting at 1.
fnoplog::resuming_afterpub fn resuming_after(highest_existing: u64) -> Selfcrates/vox-orchestrator-queue/src/oplog/mod.rs#L54-L56Create a generator whose next produced id is highest_existing + 1 (T1.3 restart-durability). Pass the highest op_id already persisted in convergence_op_log (queried via VoxDb::max_convergence_op_id) so the sequence stays monotonic across a daemon restart instead of resetting to OP-000001 and colliding with — or shadowing — history a client may have already replayed.
fnoplog::nextpub fn next(&self) -> OperationIdcrates/vox-orchestrator-queue/src/oplog/mod.rs#L59-L61Produce the next unique [OperationId].
enumoplog::OperationKindpub enum OperationKindcrates/vox-orchestrator-queue/src/oplog/mod.rs#L77The kind of operation that was performed.
structoplog::OperationEntrypub struct OperationEntrycrates/vox-orchestrator-queue/src/oplog/mod.rs#L218-L260A single entry in the operation log.
structoplog::OpLogpub struct OpLogcrates/vox-orchestrator-queue/src/oplog/mod.rs#L268-L275Append-only operation log with undo/redo support.
traitprojection::Projectionpub trait Projection: Send + Sync + Anycrates/vox-orchestrator-queue/src/projection.rs#L14-L26—
enumprojection::ProjectionErrorpub enum ProjectionErrorcrates/vox-orchestrator-queue/src/projection.rs#L29-L32—
structprojection::ProjectionRegistrypub struct ProjectionRegistrycrates/vox-orchestrator-queue/src/projection.rs#L36-L38Registry of all active projections for a daemon instance.
fnprojection::newpub fn new() -> Selfcrates/vox-orchestrator-queue/src/projection.rs#L41-L43—
fnprojection::withpub fn with<P: Projection + 'static>(mut self, p: P) -> Selfcrates/vox-orchestrator-queue/src/projection.rs#L46-L49Register a projection. Returns self for builder-style chaining.
fnprojection::applypub async fn apply(&self, entry: &OperationEntry)crates/vox-orchestrator-queue/src/projection.rs#L55-L59Apply an op to every registered projection. Async so callers can await without blocking the executor, even though the current implementation is synchronous internally.
fnprojection::snapshot_blake3pub fn snapshot_blake3(&self) -> [u8; 32]crates/vox-orchestrator-queue/src/projection.rs#L63-L65Blake3 over the concatenated deterministic snapshots of all projections. Two registries with identical state sequences must return identical hashes.
fnprojection::snapshot_bytespub fn snapshot_bytes(&self) -> Vec<u8>crates/vox-orchestrator-queue/src/projection.rs#L73-L84Deterministically encode every registered projection’s snapshot() output into a single byte buffer, framed as (name_len, name, buf_len, buf)* in registration order. This is the exact byte sequence [Self::snapshot_blake3] hashes, so re-hashing the buffer this returns always reproduces the same digest — the buffer is what a checkpoint blob stores, and [Self::restore_bytes] is its inverse.
fnprojection::restore_bytespub fn restore_bytes(&self, mut buf: &[u8]) -> Result<(), ProjectionError>crates/vox-orchestrator-queue/src/projection.rs#L90-L109Inverse of [Self::snapshot_bytes]: split the framed buffer back into per-projection slices and call [Projection::restore] on each registered projection whose name matches a frame. Frames for names with no registered projection are skipped (forward-compatible with future projections).
fnsync_lock::rw_readpub fn rw_read<'a, T>(lock: &'a StdRwLock<T>) -> StdRwLockReadGuard<'a, T>crates/vox-orchestrator-queue/src/sync_lock.rs#L13-L15Read side of a [StdRwLock], recovering after poisoning.
fnsync_lock::rw_writepub fn rw_write<'a, T>(lock: &'a StdRwLock<T>) -> StdRwLockWriteGuard<'a, T>crates/vox-orchestrator-queue/src/sync_lock.rs#L18-L20Write side of a [StdRwLock], recovering after poisoning.