jetro_core/introspect/
report.rs

1use serde::{Deserialize, Serialize};
2
3/// How much data an explicit inspection call should collect.
4#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
5pub enum InspectLevel {
6    /// Cheap high-level labels.
7    Summary,
8    /// Adds the physical plan DAG and execution facts.
9    Plan,
10    /// Adds lowering, pipeline, NDJSON, and direct-plan details.
11    Detailed,
12}
13
14/// Planning context used for static inspection.
15#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
16pub enum InspectContext {
17    /// Normal value-domain planning.
18    Value,
19    /// Byte/tape-domain planning for byte-backed documents.
20    Bytes,
21    /// NDJSON reader capabilities.
22    NdjsonReader,
23    /// NDJSON file capabilities.
24    NdjsonFile,
25}
26
27/// Options for explicit query inspection.
28#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
29pub struct InspectOptions {
30    pub level: InspectLevel,
31    pub context: InspectContext,
32}
33
34impl InspectOptions {
35    pub fn summary(context: InspectContext) -> Self {
36        Self {
37            level: InspectLevel::Summary,
38            context,
39        }
40    }
41
42    pub fn plan(context: InspectContext) -> Self {
43        Self {
44            level: InspectLevel::Plan,
45            context,
46        }
47    }
48
49    pub fn detailed(context: InspectContext) -> Self {
50        Self {
51            level: InspectLevel::Detailed,
52            context,
53        }
54    }
55}
56
57impl Default for InspectOptions {
58    fn default() -> Self {
59        Self::plan(InspectContext::Value)
60    }
61}
62
63/// Complete static inspection report for a query.
64#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
65pub struct QueryInspection {
66    pub query: String,
67    pub context: InspectContext,
68    pub level: InspectLevel,
69    pub summary: InspectionSummary,
70    pub logical: Option<LogicalInspection>,
71    pub physical: Option<PhysicalInspection>,
72    pub pipeline: Option<PipelineInspection>,
73    pub ndjson: Option<NdjsonInspection>,
74    pub warnings: Vec<String>,
75}
76
77/// One-screen summary for quick developer checks.
78#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
79pub struct InspectionSummary {
80    pub root: String,
81    pub selected_executor: Option<BackendKind>,
82    pub materializes_root: bool,
83    pub contains_vm_fallback: bool,
84    pub can_run_byte_native: bool,
85}
86
87/// Logical/lowering details that are useful before physical execution.
88#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
89pub struct LogicalInspection {
90    pub ast_root: String,
91    pub root_shape: String,
92    pub notes: Vec<String>,
93}
94
95/// Physical DAG exported from the real `QueryPlan`.
96#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
97pub struct PhysicalInspection {
98    pub root: String,
99    pub nodes: Vec<PhysicalNodeInspection>,
100}
101
102#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
103pub struct PhysicalNodeInspection {
104    pub id: usize,
105    pub kind: String,
106    pub children: Vec<usize>,
107    pub facts: ExecutionFactsInspection,
108    pub backends: Vec<BackendInspection>,
109    pub detail: Option<String>,
110}
111
112#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
113pub struct ExecutionFactsInspection {
114    pub can_avoid_root_materialization: bool,
115    pub contains_vm_fallback: bool,
116    pub can_run_byte_native: bool,
117}
118
119#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
120pub struct BackendInspection {
121    pub backend: BackendKind,
122    pub status: BackendStatus,
123    pub reason: Option<String>,
124}
125
126#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
127pub enum BackendKind {
128    ByteNative,
129    StructuralIndex,
130    TapePath,
131    ViewPipeline,
132    TapeRows,
133    ValView,
134    MaterializedSource,
135    FastChildren,
136    Pipeline,
137    Interpreted,
138    Vm,
139    NdjsonRows,
140    NdjsonRowLocal,
141}
142
143#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
144pub enum BackendStatus {
145    Planned,
146    Selected,
147    Fallback,
148    Rejected,
149}
150
151/// Pipeline lowering summary.
152#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
153pub struct PipelineInspection {
154    pub source: String,
155    pub stages: Vec<PipelineStageInspection>,
156    pub sink: String,
157    pub source_demand: String,
158    pub fallback_boundary: Option<String>,
159    pub execution_path: Option<String>,
160}
161
162#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
163pub struct PipelineStageInspection {
164    pub index: usize,
165    pub kind: String,
166    pub detail: Option<String>,
167}
168
169/// NDJSON-specific static route and row-stream details.
170#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
171pub struct NdjsonInspection {
172    pub route_kind: String,
173    pub source: String,
174    pub fallback_reason: Option<String>,
175    pub writer_path: Option<String>,
176    pub rows: Option<RowStreamInspection>,
177    pub direct_plans: Vec<DirectPlanInspection>,
178}
179
180#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
181pub struct RowStreamInspection {
182    pub plan_kind: String,
183    pub source: String,
184    pub direction: String,
185    pub demand: String,
186    pub file_strategy: Option<String>,
187    pub stages: Vec<PipelineStageInspection>,
188    pub sink: String,
189}
190
191#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
192pub struct DirectPlanInspection {
193    pub kind: String,
194    pub detail: Option<String>,
195}
jetro_core/introspect/report.rs

jetro_core/introspect/
report.rs
