Struct MerkleLedger 

pub struct MerkleLedger { /* private fields */ }

Merkle Ledger using DuckDB for persistence

Implementations

impl MerkleLedger

pub fn new() -> Result<Self>

Create a new ledger (opens or creates database)

pub fn in_memory() -> Result<Self>

Create an in-memory ledger (for testing)

pub fn start_session( &mut self, session_id: &str, task: &str, working_dir: &str, ) -> Result<()>

Start a new session

pub fn record_energy( &self, node_id: &str, energy: &EnergyComponents, total_energy: f32, ) -> Result<()>

Record energy measurement

pub fn commit_node( &mut self, node_id: &str, merkle_root: [u8; 32], _parent_hash: Option<[u8; 32]>, energy: f32, state_json: String, ) -> Result<String>

Commit a stable node state

pub fn commit_node_snapshot( &mut self, payload: &NodeCommitPayload, ) -> Result<String>

Commit a full node snapshot with all Phase 8 metadata.

This is the preferred commit API for the orchestrator. It records the complete node state, graph-structural fields, retry/error metadata, and merkle material in a single durable write. Returns the commit ID.

pub fn end_session(&mut self, status: &str) -> Result<()>

End the current session

pub fn artifacts_dir(&self) -> Option<&Path>

Get artifacts directory

pub fn get_stats(&self) -> LedgerStats

Get session statistics (legacy facade)

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

Get the current merkle root (legacy facade)

pub fn record_llm_request( &self, model: &str, prompt: &str, response: &str, node_id: Option<&str>, latency_ms: i32, tokens_in: i32, tokens_out: i32, ) -> Result<()>

Record an LLM request/response for debugging and cost tracking

pub fn record_llm_usage( &self, model: &str, node_id: Option<&str>, latency_ms: i32, tokens_in: i32, tokens_out: i32, ) -> Result<()>

Record lightweight LLM usage metrics (no prompt/response text).

This is always called after every LLM invocation regardless of the --log-llm flag so that token and cost accounting is never lost.

pub fn store(&self) -> &SessionStore

Get access to the underlying store (for direct queries)

pub fn record_structural_digest( &self, node_id: &str, source_path: &str, artifact_kind: &str, hash: &[u8], version: i32, ) -> Result<()>

Record a structural digest for a node

pub fn record_context_provenance( &self, provenance: &ContextProvenance, ) -> Result<()>

Record context provenance for a node

pub fn get_context_provenance( &self, node_id: &str, ) -> Result<Option<ContextProvenanceRecord>>

Get context provenance for a specific node in the current session

pub fn record_escalation_report(&self, report: &EscalationReport) -> Result<()>

Record an escalation report for a non-convergent node

pub fn record_rewrite(&self, record: &RewriteRecord) -> Result<()>

Record a local graph rewrite

pub fn get_rewrite_count_for_lineage(&self, lineage_base: &str) -> Result<usize>

PSP-5 Phase 5: Count rewrite records matching a lineage prefix.

A lineage is identified by the base node ID (before any __split_ or __iface suffixes). This count is used as a churn guardrail to prevent infinite rewrite loops.

pub fn record_sheaf_validation( &self, node_id: &str, result: &SheafValidationResult, ) -> Result<()>

Record a sheaf validation result

pub fn get_escalation_reports(&self) -> Result<Vec<EscalationReportRecord>>

Get escalation reports for the current session

pub fn record_verification_result( &self, node_id: &str, result: &VerificationResult, ) -> Result<()>

Record a verification result snapshot for a node

pub fn get_verification_result( &self, node_id: &str, ) -> Result<Option<VerificationResultRow>>

Get the latest verification result for a node

pub fn record_artifact_bundle( &self, node_id: &str, bundle: &ArtifactBundle, ) -> Result<()>

Record an artifact bundle snapshot for a node

pub fn get_artifact_bundle( &self, node_id: &str, ) -> Result<Option<ArtifactBundleRow>>

Get the latest artifact bundle for a node

pub fn record_task_graph_edge( &self, parent_node_id: &str, child_node_id: &str, edge_type: &str, ) -> Result<()>

Record a task-graph edge (parent→child dependency)

pub fn get_task_graph_edges(&self) -> Result<Vec<TaskGraphEdgeRow>>

Get all task graph edges for the current session

pub fn get_sheaf_validations( &self, node_id: &str, ) -> Result<Vec<SheafValidationRow>>

Get sheaf validations for a specific node

pub fn load_session_snapshot(&self) -> Result<SessionSnapshot>

Load a complete session snapshot for rehydration/resume.

Aggregates the latest node states, graph topology, energy history, verification results, artifact bundles, sheaf validations, provisional branches, interface seals, context provenance, and escalation reports into a single SessionSnapshot.

pub fn record_provisional_branch( &self, branch: &ProvisionalBranch, ) -> Result<()>

Record a new provisional branch for speculative child work

pub fn update_branch_state( &self, branch_id: &str, new_state: &str, ) -> Result<()>

Update a provisional branch state

pub fn get_provisional_branches(&self) -> Result<Vec<ProvisionalBranchRow>>

Get all provisional branches for the current session

pub fn get_live_branches_for_parent( &self, parent_node_id: &str, ) -> Result<Vec<ProvisionalBranchRow>>

Get live (active/sealed) branches depending on a parent node

pub fn flush_branches_for_parent( &self, parent_node_id: &str, ) -> Result<Vec<String>>

Flush all live branches for a parent node and return flushed branch IDs

pub fn record_branch_lineage(&self, lineage: &BranchLineage) -> Result<()>

Record a branch lineage edge (parent branch → child branch)

pub fn record_interface_seal(&self, seal: &InterfaceSealRecord) -> Result<()>

Record an interface seal for a node

pub fn get_interface_seals( &self, node_id: &str, ) -> Result<Vec<InterfaceSealRow>>

Get all interface seals for a node in the current session

pub fn record_branch_flush(&self, flush: &BranchFlushRecord) -> Result<()>

Record a branch flush decision

pub fn get_branch_flushes(&self) -> Result<Vec<BranchFlushRow>>

Get all branch flush records for the current session

pub fn record_review_outcome( &self, node_id: &str, outcome: &str, reviewer_note: Option<&str>, energy_at_review: Option<f64>, degraded: Option<bool>, escalation_category: Option<&str>, ) -> Result<()>

Persist a review decision as an audit record.

pub fn get_review_outcomes( &self, node_id: &str, ) -> Result<Vec<ReviewOutcomeRow>>

Get all review outcomes for a node.

pub fn get_all_review_outcomes(&self) -> Result<Vec<ReviewOutcomeRow>>

Get all review outcomes across the session.

pub fn node_review_summary(&self, node_id: &str) -> Result<NodeReviewSummary>

Build a review-ready summary for a single node.

Aggregates energy history, escalation reports, sheaf validations, context provenance, interface seals, and branch state from the store into a single struct consumable by both TUI and CLI surfaces.

pub fn session_summary(&self) -> Result<SessionReviewSummary>

Build a session-level summary aggregating lifecycle counts, energy stats, escalation activity, and branch provenance.

impl MerkleLedger

pub fn record_feature_charter(&self, charter: &FeatureCharter) -> Result<()>

Record a feature charter for the current session.

pub fn get_feature_charter(&self) -> Result<Option<FeatureCharterRow>>

Get the feature charter for the current session.

pub fn record_plan_revision(&self, revision: &PlanRevision) -> Result<()>

Record a plan revision for the current session.

pub fn get_active_plan_revision(&self) -> Result<Option<PlanRevisionRow>>

Get the active plan revision for the current session.

pub fn get_plan_revisions(&self) -> Result<Vec<PlanRevisionRow>>

Get all plan revisions for the current session.

pub fn supersede_plan_revision(&self, revision_id: &str) -> Result<()>

Supersede a plan revision by ID.

pub fn record_repair_footprint(&self, footprint: &RepairFootprint) -> Result<()>

Record a repair footprint for a node.

pub fn get_repair_footprints( &self, node_id: &str, ) -> Result<Vec<RepairFootprintRow>>

Get repair footprints for a node in the current session.

pub fn upsert_budget_envelope(&self, budget: &BudgetEnvelope) -> Result<()>

Record or update the budget envelope for the current session.

pub fn get_budget_envelope(&self) -> Result<Option<BudgetEnvelopeRow>>

Get the budget envelope for the current session.

pub fn record_step(&self, record: &SrbnStepRecord) -> Result<()>

Record an orchestration step transition for the current session.

pub fn get_step_timeline(&self, node_id: &str) -> Result<Vec<SrbnStepRecord>>

Retrieve the step timeline for a node in the current session.

pub fn get_session_steps(&self) -> Result<Vec<SrbnStepRecord>>

Retrieve all step records for the current session.

pub fn record_correction_attempt( &self, record: &CorrectionAttemptRow, ) -> Result<()>

Record a correction attempt for the current session.

pub fn get_correction_attempts( &self, node_id: &str, ) -> Result<Vec<CorrectionAttemptRow>>

Retrieve all correction attempts for a node in the current session.