Struct TreeManager 

pub struct TreeManager { /* private fields */ }

Unified facade over ResourceTree + MutationLog + ChainManager.

Every mutating operation on the tree also:

1. Appends a MutationEvent to the mutation log
2. Appends a ChainEvent to the chain
3. Stores chain_seq metadata on the affected tree node

Implementations

impl TreeManager

pub fn new(chain: Arc<ChainManager>) -> Self

Create a new TreeManager with an empty tree and mutation log.

pub fn set_signing_key(&mut self, key: SigningKey)

Set the Ed25519 signing key for signing tree mutations. When set, all mutations will have their signature field populated.

pub fn mutation_canonical_bytes( operation: &str, path: &str, timestamp: &DateTime<Utc>, ) -> Vec<u8>

Build the canonical bytes for a mutation signature.

Format: "<operation>|<path>|<timestamp_rfc3339>" encoded as UTF-8.

pub fn mutation_sign_parts(event: &MutationEvent) -> Option<MutationSignParts>

Extract (operation, path, timestamp, signature) from a mutation event.

pub fn verify_mutation_signature( event: &MutationEvent, pubkey: &VerifyingKey, ) -> Result<(), Box<dyn Error + Send + Sync>>

Verify an Ed25519 signature on a mutation event (WEFT-144).

Returns Ok(()) when the signature is present and valid under pubkey. Errors when the signature is missing, malformed, or does not verify.

pub fn bootstrap(&self) -> Result<(), Box<dyn Error + Send + Sync>>

Bootstrap the tree with well-known WeftOS namespaces.

Creates the standard namespace hierarchy (/kernel, /kernel/services, etc.), logs a MutationEvent::Create for each bootstrapped node, and appends a tree.bootstrap chain event with node count and root hash.

pub fn insert( &self, id: ResourceId, kind: ResourceKind, parent: ResourceId, ) -> Result<(), Box<dyn Error + Send + Sync>>

Insert a new resource node into the tree.

Creates the tree node, appends a MutationEvent::Create, appends a tree.insert chain event, and stores the chain sequence number as metadata on the node for two-way traceability.

pub fn remove(&self, id: ResourceId) -> Result<(), Box<dyn Error + Send + Sync>>

Remove a leaf node from the tree.

Removes the node, appends a MutationEvent::Remove and a tree.remove chain event.

pub fn update_meta( &self, id: &ResourceId, key: &str, value: Value, ) -> Result<(), Box<dyn Error + Send + Sync>>

Update metadata on a resource node.

Sets the key-value pair on the node, appends a MutationEvent::UpdateMeta and a tree.update_meta chain event.

pub fn register_service( &self, name: &str, ) -> Result<(), Box<dyn Error + Send + Sync>>

Register a service in the tree, creating /kernel/services/{name}.

This is the unified path for service registration: it inserts the tree node AND creates the chain event atomically.

pub fn register_service_with_manifest( &self, name: &str, service_type: &str, ) -> Result<(), Box<dyn Error + Send + Sync>>

Register a service with a manifest chain event.

Inserts the tree node and emits an additional service.manifest chain event with structured metadata (name, type, tree path, registration time). This produces an RVF-auditable registration when the chain is persisted as RVF segments.

pub fn register_agent( &self, agent_id: &str, pid: Pid, caps: &AgentCapabilities, ) -> Result<(), Box<dyn Error + Send + Sync>>

Register an agent in the tree, creating /kernel/agents/{agent_id}.

Creates the tree node with kind Agent, sets metadata (pid, state, spawn_time), and emits an agent.spawn chain event.

pub fn unregister_agent( &self, agent_id: &str, pid: Pid, exit_code: i32, ) -> Result<(), Box<dyn Error + Send + Sync>>

Unregister an agent from the tree.

Updates the tree node metadata (state=exited, exit_code, stop_time) and emits an agent.stop chain event. Does NOT remove the node (preserves audit trail).

pub fn update_agent_state( &self, agent_id: &str, state: &str, ) -> Result<(), Box<dyn Error + Send + Sync>>

Update an agent’s state in the tree.

pub fn tree(&self) -> &Mutex<ResourceTree>

Get direct access to the resource tree (for read-only queries).

pub fn mutation_log(&self) -> &Mutex<MutationLog>

Get direct access to the mutation log.

pub fn chain(&self) -> &Arc<ChainManager>

Get the chain manager.

pub fn root_hash(&self) -> [u8; 32]

Get the root hash of the resource tree.

pub fn stats(&self) -> TreeStats

Get a statistics snapshot.

pub fn update_scoring( &self, id: &ResourceId, scoring: NodeScoring, ) -> Result<(), Box<dyn Error + Send + Sync>>

Set the scoring vector for a node.

Updates the tree, logs a MutationEvent::UpdateScoring, and emits a scoring.update chain event.

pub fn blend_scoring( &self, id: &ResourceId, observation: &NodeScoring, alpha: f32, ) -> Result<(), Box<dyn Error + Send + Sync>>

EMA-blend an observation into a node’s scoring.

Emits a scoring.blend chain event.

pub fn get_scoring(&self, id: &ResourceId) -> Option<NodeScoring>

Get the scoring vector for a node.

pub fn find_similar( &self, target_id: &ResourceId, count: usize, ) -> Vec<(ResourceId, f32)>

Find nodes most similar to a target node by cosine similarity.

Returns up to count (ResourceId, similarity) pairs sorted by descending similarity.

pub fn rank_by_score( &self, weights: &[f32; 6], count: usize, ) -> Vec<(ResourceId, f32)>

Rank all nodes by weighted score.

Returns up to count (ResourceId, weighted_score) pairs sorted by descending score.

pub fn build_tool( &self, name: &str, wasm_bytes: &[u8], signing_key: &SigningKey, ) -> Result<ToolVersion, Box<dyn Error + Send + Sync>>

Build a tool: validate WASM bytes, compute hash, sign with Ed25519.

Returns a ToolVersion with the computed module hash and Ed25519 signature. Emits a tool.build chain event.

pub fn deploy_tool( &self, spec: &BuiltinToolSpec, version: &ToolVersion, ) -> Result<(), Box<dyn Error + Send + Sync>>

Deploy a tool to the resource tree.

Creates the tool node at /kernel/tools/{category}/{name}, stores version metadata, and emits a tool.deploy chain event.

pub fn update_tool_version( &self, name: &str, new_version: &ToolVersion, ) -> Result<(), Box<dyn Error + Send + Sync>>

Update a tool to a new version.

Updates the tool node’s metadata with new version info and emits a tool.version.update chain event linking old to new.

pub fn revoke_tool_version( &self, name: &str, version: u32, ) -> Result<(), Box<dyn Error + Send + Sync>>

Revoke a tool version.

Marks the specified version as revoked in metadata. Does NOT delete the tree node (preserves audit trail). Emits a tool.version.revoke chain event.

pub fn get_tool_versions(&self, name: &str) -> Vec<Value>

Query version history for a tool (K4 B2).

Returns the list of version entries persisted in the tree metadata, or an empty vec if the tool has no versions.

pub fn save_checkpoint( &self, path: &Path, ) -> Result<(), Box<dyn Error + Send + Sync>>

Save tree state to a checkpoint file on disk.

Serializes the tree via exo_resource_tree::to_checkpoint() and writes the bytes to the given path.

pub fn load_checkpoint( &self, path: &Path, ) -> Result<(), Box<dyn Error + Send + Sync>>

Load tree state from a checkpoint file.

Reads the file, deserializes via exo_resource_tree::from_checkpoint(), and replaces the internal tree. The mutation log is cleared.

pub fn checkpoint(&self) -> Result<Value, Box<dyn Error + Send + Sync>>

Create a combined checkpoint of tree + mutation log + chain state.

Returns JSON with the tree checkpoint, mutation count, and chain checkpoint info. Full checkpoint persistence is a K1 concern.

pub fn snapshot(&self) -> Result<TreeSnapshot, Box<dyn Error + Send + Sync>>

Create a serializable snapshot of the full tree state. Used for cross-node tree synchronization in K6.4.

pub fn apply_remote_mutation( &self, event: MutationEvent, ) -> Result<(), Box<dyn Error + Send + Sync>>

Apply a remote mutation received from a peer node. Records the mutation in the local log.

Does not verify signatures — prefer Self::apply_remote_mutation_verified for cross-node events (WEFT-144). Kept for local/unsigned bootstrap paths.

pub fn apply_remote_mutation_verified( &self, event: MutationEvent, peer_pubkey: &VerifyingKey, ) -> Result<(), Box<dyn Error + Send + Sync>>

Apply a remote mutation after verifying its Ed25519 signature against the peer’s public key (WEFT-144).

Rejects missing, malformed, and invalid signatures. Create is idempotent when the node already exists (replay-safe).

pub fn merkle_diff( &self, other: &TreeManager, ) -> Result<MerkleDiff, Box<dyn Error + Send + Sync>>

Compute a minimal Merkle diff of self against other.

Only subtrees whose hashes differ are visited (O(changed), not O(tree)).

pub fn merkle_proof( &self, id: &ResourceId, ) -> Result<Option<MerkleInclusionProof>, Box<dyn Error + Send + Sync>>

Generate a Merkle inclusion proof for a resource path.

pub fn verify_merkle_proof( &self, proof: &MerkleInclusionProof, ) -> Result<bool, Box<dyn Error + Send + Sync>>

Verify a Merkle inclusion proof against this tree’s root.

pub fn signed_events_for_diff( &self, diff: &MerkleDiff, ) -> Result<Vec<MutationEvent>, Box<dyn Error + Send + Sync>>

Collect signed mutation events from the local log that touch paths in diff (Added / Modified / Removed). Used to ship authenticated deltas alongside a MerkleDiff (WEFT-106 + WEFT-144).

pub fn apply_merkle_diff_verified( &self, diff: &MerkleDiff, signed_events: &[MutationEvent], peer_pubkey: &VerifyingKey, ) -> Result<usize, Box<dyn Error + Send + Sync>>

Apply a peer’s Merkle diff using verified signed mutation events (WEFT-106 wired to WEFT-144 apply_remote_mutation_verified).

Events are applied in log order. Each must carry a valid Ed25519 signature under peer_pubkey. After structural events, node payloads from the diff (metadata / scoring) are reconciled so Merkle roots converge — MutationEvent::Create does not carry full metadata, so the minimal-witness payload is authoritative for those fields once the path is authenticated by a signed Create/Update.

pub fn tree_sync_response_from_diff( &self, diff: &MerkleDiff, ) -> Result<TreeSyncResponse, Box<dyn Error + Send + Sync>>

Build a mesh crate::mesh_tree::TreeSyncResponse from a MerkleDiff.

Trait Implementations

impl Debug for TreeManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.