m1nd_core/
error.rs

1// === crates/m1nd-core/src/error.rs ===
2
3use crate::types::{EdgeIdx, Generation, NodeId};
4
5/// Central error type covering all failure modes from 05-HARDENING-SYNTHESIS.
6/// Each variant references its FM-ID for traceability.
7#[derive(Debug, thiserror::Error)]
8pub enum M1ndError {
9    // --- Graph integrity ---
10    /// FM-ACT-011: Edge references a node index that does not exist.
11    #[error("dangling edge: edge {edge:?} references non-existent node {node:?}")]
12    DanglingEdge { edge: EdgeIdx, node: NodeId },
13
14    /// FM-PL-006: Graph structure changed since engine was initialised.
15    #[error("graph generation mismatch: expected {expected:?}, actual {actual:?}")]
16    GraphGenerationMismatch {
17        expected: Generation,
18        actual: Generation,
19    },
20
21    /// FM-ACT-016: Attempted to add a node whose interned ID already exists.
22    #[error("duplicate node: interned ID {0:?}")]
23    DuplicateNode(NodeId),
24
25    /// Graph not finalised — CSR not built yet.
26    #[error("graph not finalised: call Graph::finalize() before queries")]
27    GraphNotFinalized,
28
29    /// Graph is empty (zero nodes).
30    #[error("graph is empty")]
31    EmptyGraph,
32
33    // --- Numerical safety ---
34    /// FM-PL-001: Non-finite value detected at a NaN firewall boundary.
35    #[error("non-finite value at firewall: node={node:?}, value={value}")]
36    NonFiniteActivation { node: NodeId, value: f32 },
37
38    /// FM-ACT-012: A tuneable parameter is outside its valid range.
39    #[error("parameter out of range: {name} = {value} (expected {range})")]
40    ParameterOutOfRange {
41        name: &'static str,
42        value: f64,
43        range: &'static str,
44    },
45
46    /// FM-RES-001: Zero or negative wavelength/frequency supplied.
47    #[error("non-positive resonance parameter: {name} = {value}")]
48    NonPositiveResonanceParam { name: &'static str, value: f32 },
49
50    // --- Resource exhaustion ---
51    /// FM-RES-004: Pulse propagation exceeded budget.
52    #[error("pulse budget exhausted: {budget} pulses processed")]
53    PulseBudgetExhausted { budget: u64 },
54
55    /// FM-TMP-005: Causal chain DFS exceeded budget.
56    #[error("chain budget exhausted: {budget} chains generated")]
57    ChainBudgetExhausted { budget: u64 },
58
59    /// FM-TMP-001: Co-change sparse matrix exceeded entry budget.
60    #[error("matrix entry budget exhausted: {budget} entries")]
61    MatrixBudgetExhausted { budget: u64 },
62
63    /// FM-ING-002: Ingestion exceeded timeout.
64    #[error("ingestion timeout after {elapsed_s:.1}s")]
65    IngestionTimeout { elapsed_s: f64 },
66
67    /// FM-ING-002: Ingestion exceeded node count budget.
68    #[error("ingestion node budget exhausted: {budget} nodes")]
69    IngestionNodeBudget { budget: u64 },
70
71    /// FM-TOP-014: Fingerprint pair budget exceeded.
72    #[error("fingerprint pair budget exhausted: {budget} pairs")]
73    FingerprintPairBudget { budget: u64 },
74
75    // --- Analysis quality ---
76    /// FM-XLR-010: XLR cancelled all signal — fallback to hot-only.
77    #[error("XLR over-cancellation: all signal cancelled")]
78    XlrOverCancellation,
79
80    /// FM-TOP-003: Louvain community detection did not converge.
81    #[error("Louvain non-convergence after {passes} passes")]
82    LouvainNonConvergence { passes: u32 },
83
84    /// FM-TOP-010: Power iteration may have diverged.
85    #[error("spectral analysis: power iteration divergence suspected")]
86    SpectralDivergence,
87
88    /// FM-RES-020: Division by zero in normalization (max_amp == 0).
89    #[error("resonance normalization: max amplitude is zero")]
90    ResonanceZeroAmplitude,
91
92    /// FM-ACT-019: Atomic CAS retry limit exceeded during concurrent weight update.
93    #[error("CAS retry limit ({limit}) exceeded at edge {edge:?}")]
94    CasRetryExhausted { edge: EdgeIdx, limit: u32 },
95
96    // --- Ingestion ---
97    /// FM-ING-003: File encoding could not be determined.
98    #[error("encoding detection failed for {path} (confidence={confidence:.2})")]
99    EncodingDetectionFailed { path: String, confidence: f32 },
100
101    /// FM-ING-004: Binary file detected and skipped.
102    #[error("binary file skipped: {path}")]
103    BinaryFileSkipped { path: String },
104
105    /// FM-ING-008: Label collision — multiple nodes share a label.
106    #[error("label collision: {label} maps to {count} nodes")]
107    LabelCollision { label: String, count: usize },
108
109    // --- Persistence ---
110    /// FM-PL-007: Corrupt state file on load.
111    #[error("corrupt persistence state: {reason}")]
112    CorruptState { reason: String },
113
114    /// FM-PL-009: Schema drift — edge identity mismatch on import.
115    #[error("schema drift on import: {reason}")]
116    SchemaDrift { reason: String },
117
118    // --- Counterfactual ---
119    /// FM-CF-001: Seed node was in the removal set.
120    #[error("counterfactual seed overlap: seed {node:?} is in the removal set")]
121    CounterfactualSeedOverlap { node: NodeId },
122
123    // --- Perspective / Lock / Navigation (12-PERSPECTIVE-SYNTHESIS Theme 3) ---
124    /// Theme 3: Unknown tool name in dispatch.
125    #[error("unknown tool: {name}")]
126    UnknownTool { name: String },
127
128    /// Theme 3: Invalid parameters for a tool call.
129    #[error("invalid params for {tool}: {detail}")]
130    InvalidParams { tool: String, detail: String },
131
132    /// Theme 3: Perspective does not exist for agent.
133    #[error("perspective not found: {perspective_id} for agent {agent_id}")]
134    PerspectiveNotFound {
135        perspective_id: String,
136        agent_id: String,
137    },
138
139    /// Theme 3: Perspective route set is stale (generation mismatch).
140    #[error(
141        "perspective stale: {perspective_id} expected gen {expected_gen}, actual {actual_gen}"
142    )]
143    PerspectiveStale {
144        perspective_id: String,
145        expected_gen: u64,
146        actual_gen: u64,
147    },
148
149    /// Theme 3: Agent exceeded max perspective count.
150    #[error("perspective limit exceeded for agent {agent_id}: {current}/{limit}")]
151    PerspectiveLimitExceeded {
152        agent_id: String,
153        current: usize,
154        limit: usize,
155    },
156
157    /// Theme 3: Route set version mismatch (stale cached routes).
158    #[error("route set stale: version {route_set_version}, current {current_version}")]
159    RouteSetStale {
160        route_set_version: u64,
161        current_version: u64,
162    },
163
164    /// Theme 3: Route not found in perspective.
165    #[error("route not found: {route_id} in perspective {perspective_id}")]
166    RouteNotFound {
167        route_id: String,
168        perspective_id: String,
169    },
170
171    /// Theme 3: Cannot navigate back — already at root.
172    #[error("navigation at root: perspective {perspective_id}")]
173    NavigationAtRoot { perspective_id: String },
174
175    /// Theme 3: Branch depth limit exceeded.
176    #[error("branch depth exceeded in {perspective_id}: depth {depth}/{limit}")]
177    BranchDepthExceeded {
178        perspective_id: String,
179        depth: usize,
180        limit: usize,
181    },
182
183    /// Theme 3: Lock not found.
184    #[error("lock not found: {lock_id}")]
185    LockNotFound { lock_id: String },
186
187    /// Theme 3: Lock ownership violation.
188    #[error("lock ownership violation: {lock_id} owned by {owner}, called by {caller}")]
189    LockOwnership {
190        lock_id: String,
191        owner: String,
192        caller: String,
193    },
194
195    /// Theme 3: Lock scope too large (BFS budget exceeded).
196    #[error("lock scope too large: {node_count} nodes exceeds cap of {cap}")]
197    LockScopeTooLarge { node_count: usize, cap: usize },
198
199    /// Theme 3: Agent exceeded max lock count.
200    #[error("lock limit exceeded for agent {agent_id}: {current}/{limit}")]
201    LockLimitExceeded {
202        agent_id: String,
203        current: usize,
204        limit: usize,
205    },
206
207    /// Theme 3: Watcher strategy not supported (e.g. Periodic in V1).
208    #[error("watch strategy not supported: {strategy}")]
209    WatchStrategyNotSupported { strategy: String },
210
211    /// Theme 3: Affinity computation exceeded time budget.
212    #[error("affinity timeout: {elapsed_ms:.1}ms exceeded budget of {budget_ms:.1}ms")]
213    AffinityTimeout { elapsed_ms: f64, budget_ms: f64 },
214
215    // --- Antibody ---
216    /// FM-AB-001: Antibody pattern specificity below minimum threshold.
217    #[error("pattern too broad: specificity {specificity:.2} below minimum {minimum:.2}")]
218    PatternTooBroad { specificity: f32, minimum: f32 },
219
220    /// Antibody not found by ID.
221    #[error("antibody not found: {id}")]
222    AntibodyNotFound { id: String },
223
224    /// Antibody storage limit exceeded.
225    #[error("antibody limit exceeded: {current}/{limit}")]
226    AntibodyLimitExceeded { current: usize, limit: usize },
227
228    // --- Epidemic ---
229    /// Epidemic burnout: too many nodes infected too fast.
230    #[error("epidemic burnout: {infected_pct:.1}% infected in {iteration} iterations")]
231    EpidemicBurnout { infected_pct: f32, iteration: u32 },
232
233    /// No valid infected nodes provided for epidemic simulation.
234    #[error("no valid infected nodes")]
235    NoValidInfectedNodes,
236
237    // --- Flow ---
238    /// No entry points found for flow simulation.
239    #[error("no entry points found for flow simulation")]
240    NoEntryPoints,
241
242    // --- Layers ---
243    /// Layer level not found in detection result.
244    #[error("layer not found: level {level}")]
245    LayerNotFound { level: u8 },
246
247    // --- Ingestion (runtime) ---
248    /// Tree-sitter or extractor runtime error.
249    #[error("ingest error: {0}")]
250    IngestError(String),
251
252    // --- I/O ---
253    #[error("I/O error: {0}")]
254    Io(#[from] std::io::Error),
255
256    #[error("serialization error: {0}")]
257    Serde(#[from] serde_json::Error),
258
259    #[error("persistence failed: {0}")]
260    PersistenceFailed(String),
261}
262
263/// Convenience alias used throughout the crate.
264pub type M1ndResult<T> = Result<T, M1ndError>;
m1nd_core/error.rs

m1nd_core/
error.rs
