operations tier

`operations-diagnostic-engine`

Generic symptom -> ranked, evidence-backed causal-chain engine: a Collector<D> trait (best-effort probe, explicit Checked/Unavailable outcome, never silent omission), an orchestrator that runs base collectors always and conditional ones only once a trigger fires, and a pure rank() that groups evidence by key (PILEUP), sums contribution, and returns a ranked CausalChain<D>. Domain-agnostic over the evidence detail type D -- harvested out of systats (ADR 0034).

Generic symptom -> ranked, evidence-backed causal-chain engine: a Collector<D> trait (best-effort probe, explicit Checked/Unavailable outcome, never silent omission), an orchestrator that runs base collectors always and conditional ones only once a trigger fires, and a pure rank() that groups evidence by key (PILEUP), sums contribution, and returns a ranked CausalChain<D>. Domain-agnostic over the evidence detail type D -- harvested out of systats (ADR 0034).

Tier	operations
Role	unclassified (baselined)
Path	`crates/operations/diagnostic-engine`
Edition	2021
Targets	operations_diagnostic_engine
Public items	13 across 4 modules
Tests	12

What it is for

Generic symptom -> ranked, evidence-backed causal-chain engine.

Harvested out of systats (a desktop diagnostic GUI) once its data model, Collector trait, and rank() proved themselves against a real app and looked like the start of a reusable shape (ADR 0034): a Collector<D> trait for best-effort, explicitly-degrading probes; an orchestrator that runs base collectors always and conditional ones only once a trigger fires (so hop-dependent sources aren't collected eagerly); and a pure rank() that groups evidence by key, sums contribution, and returns a ranked CausalChain.

This crate owns no domain vocabulary -- no "symptom," no "process," no "sensor." Every type is generic over the caller's evidence detail type D; relevance filtering, scoring, and grouping keys are the caller's closures. See systats's own ranking.rs/orchestrator.rs for a worked specialization.

Capabilities

`CollectError`

_No module-level documentation is present in the source._

Item
`pub enum CollectError`

`CollectOutcome`

_No module-level documentation is present in the source._

Item
`pub enum CollectOutcome<D>`

`Collector`

_No module-level documentation is present in the source._

Item
`pub trait Collector<D>`

`UnavailableStubCollector`

_No module-level documentation is present in the source._

Item
`pub struct UnavailableStubCollector<D>`

`UnavailableStubCollector<D>`

_No module-level documentation is present in the source._

Item
`UnavailableStubCollector<D> :: fn new(name : & 'static str, reason : impl Into <String>) -> Self`
`UnavailableStubCollector<D> :: fn name(& self) -> & str`
`UnavailableStubCollector<D> :: fn collect(& self) -> CollectOutcome <D>`

`CausalChain`

_No module-level documentation is present in the source._

Item
`pub struct CausalChain<D>`

`CausalNode`

_No module-level documentation is present in the source._

Item
`pub struct CausalNode<D>`

`Evidence`

_No module-level documentation is present in the source._

Item
`pub struct Evidence<D>`

`OrchestrationResult`

_No module-level documentation is present in the source._

Item
`pub struct OrchestrationResult<D>`
`fn orchestrate <D>(base : & & dyn Collector <D>, trigger : impl Fn(& Evidence <D>) -> bool, conditional : & & dyn Collector <D>,) -> OrchestrationResult <D>`

`ranking (other)`

_No module-level documentation is present in the source._

Item
`fn rank <D : Clone>(evidence : & Evidence <D>, group_key : impl Fn(& D) -> Option <String>, label : impl Fn(& D) -> String, score : impl Fn(& D) -> f32,) -> CausalChain <D>`

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

operations_diagnostic_engine

collector
evidence
orchestrator
ranking

flowchart TD
  n_operations_diagnostic_engine["operations_diagnostic_engine"]
  n_operations_diagnostic_engine --> n_collector["collector"]
  n_operations_diagnostic_engine --> n_evidence["evidence"]
  n_operations_diagnostic_engine --> n_orchestrator["orchestrator"]
  n_operations_diagnostic_engine --> n_ranking["ranking"]

Public surface

`collector`

Item	What it is
`pub trait Collector<D>`	One implementation per data source
`pub enum CollectOutcome<D>`	A collector's result must be an explicit outcome, never silent omission on failure: "checked, found nothing" and "couldn't check" are different facts and both must reach the caller.
`pub enum CollectError`	Shaped like `operations-host-inventory`'s `DetectError`: a probe is best-effort, so a failure degrades to `CollectOutcome::Unavailable`, never aborts the caller's whole report.
`pub struct UnavailableStubCollector<D>`	A collector known to not be implemented yet -- distinct from a real collector that failed
`UnavailableStubCollector<D> :: fn new(name : & 'static str, reason : impl Into <String>) -> Self`	—
`UnavailableStubCollector<D> :: fn name(& self) -> & str`	—
`UnavailableStubCollector<D> :: fn collect(& self) -> CollectOutcome <D>`	—

`evidence`

Item	What it is
`pub struct Evidence<D>`	One measurement from a `crate::Collector`
`pub struct CausalChain<D>`	Ranked candidate root causes, most-culpable first
`pub struct CausalNode<D>`	One hop (or a grouped finding of several instances) in a causal chain

`orchestrator`

Item	What it is
`pub struct OrchestrationResult<D>`	The flattened result of a collection pass: `evidence` feeds `crate::rank`; `unavailable` is every `(source, reason)` a collector reported explicitly -- never silently dropped.
`fn orchestrate <D>(base : & & dyn Collector <D>, trigger : impl Fn(& Evidence <D>) -> bool, conditional : & & dyn Collector <D>,) -> OrchestrationResult <D>`	Run `base` collectors unconditionally, then -- only if `trigger` returns true against the evidence collected so far -- run `conditional` too

`ranking`

Item	What it is
`fn rank <D : Clone>(evidence : & Evidence <D>, group_key : impl Fn(& D) -> Option <String>, label : impl Fn(& D) -> String, score : impl Fn(& D) -> f32,) -> CausalChain <D>`	Pure: no I/O, no collector calls

Re-exports. Exported here, defined elsewhere.

Export	Defined in
`rank`	`ranking::rank`
`{CausalChain,CausalNode,Evidence}`	`evidence::{CausalChain,CausalNode,Evidence}`
`{CollectError,CollectOutcome,Collector,UnavailableStubCollector}`	`collector::{CollectError,CollectOutcome,Collector,UnavailableStubCollector}`
`{orchestrate,OrchestrationResult}`	`orchestrator::{orchestrate,OrchestrationResult}`

Boundary

Depends on no other workspace tier.

Shares tier operations with 40 other crates: operations-approval-workflow, operations-assessments, operations-block-imaging, operations-boot-media, operations-browser-agent-worker, operations-camera-discovery, operations-camera-liveview, operations-camera-registry, … (40 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`operations`
Architectural role (taxonomy)	`unclassified (baselined)`
Location	`crates/operations/diagnostic-engine`
Vocabulary in force (lexicon)	`current`

Dependencies

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`thiserror`	`^2`	—	no	always

Development. None.

Build. None.

Depended on by. 1 workspace crate.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_operations_crash_detector["operations-crash-detector"] -->|uses| SELF
  SELF["operations-diagnostic-engine"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
lib	`operations_diagnostic_engine`	`src/lib.rs`

Error model

Error type	Named by
`CollectError`	declared, no public signature returns it

Operational characteristics

Property	Evidence
async public surface	none detected
async runtime	none detected
database access	none detected
network I/O	none detected
unsafe code	none detected
environment variables	none detected

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

1 workspace crate depends on this one: operations-crash-detector.

Verification

Kind	Count
Unit tests	12
Integration tests	0
Examples	0
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Examples	Consumers
`collector`	4	0	3
`evidence`	3	0	1
`orchestrator`	2	0	0
`ranking`	1	0	0

What the tests establish, by name:

checked_outcome_carries_its_evidence — src/collector.rs
stub_collector_always_reports_unavailable_with_its_reason — src/collector.rs
unavailable_outcome_is_explicit_not_silently_dropped — src/collector.rs
deny_orchestrate_surfaces_collector_failure_not_silently — src/orchestrator.rs
valid_orchestrate_with_trigger_runs_conditional_collectors — src/orchestrator.rs
valid_orchestrate_without_trigger_skips_conditional_collectors — src/orchestrator.rs
boundary_empty_evidence_yields_empty_chain — src/ranking.rs
boundary_single_evidence_yields_single_candidate — src/ranking.rs
constraint_ties_broken_deterministically_by_label — src/ranking.rs
deny_no_group_key_never_groups_even_with_identical_labels — src/ranking.rs
pileup_rule_groups_shared_key_into_one_finding_with_instance_evidence — src/ranking.rs
valid_ranking_orders_by_contribution_most_culpable_first — src/ranking.rs

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	10	13
Public modules with a `//!` block	0	4

pie showData
    title Public items with rustdoc
    "Documented" : 10
    "No rustdoc detected" : 3

Metrics

Metric	Value
Rust source files	5
Source lines	530
Code lines	405
Public API items	13
Public modules	4
Tests	12
Examples	0
Cargo features	0
Direct runtime dependencies	1
Workspace reverse dependencies	1

pie showData
    title Public API by kind
    "enum" : 2
    "function" : 2
    "method" : 3
    "struct" : 5
    "trait" : 1

pie showData
    title Rust source composition
    "Code" : 405
    "Blank or comment" : 125

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

All operations · Manual