vyre_runtime/megakernel/planner/caps.rs
1//! Megakernel backend capability and report types.
2
3use std::time::Duration;
4
5use super::super::policy::{ResidentExecutionMode, ResidentQueuePressure, ResidentQueueTopology};
6
7/// Capabilities surfaced by megakernel-aware backends.
8#[derive(Debug, Clone, Copy)]
9pub struct ResidentQueueCapabilities {
10 /// Whether the backend implements a megakernel path.
11 pub supported: bool,
12 /// Maximum worker-count ceiling the backend accepts.
13 pub max_worker_count: u32,
14}
15
16impl ResidentQueueCapabilities {
17 /// Unsupported - every method returns an explicit error.
18 #[must_use]
19 pub const fn unsupported() -> Self {
20 Self {
21 supported: false,
22 max_worker_count: 0,
23 }
24 }
25
26 /// Declare supported with the given worker ceiling.
27 #[must_use]
28 pub const fn supported(max_worker_count: u32) -> Self {
29 Self {
30 supported: true,
31 max_worker_count,
32 }
33 }
34}
35
36/// One work-queue item the megakernel worker consumes.
37#[repr(C)]
38#[derive(Debug, Clone, Copy, PartialEq, Eq, bytemuck::Pod, bytemuck::Zeroable)]
39pub struct ResidentWorkItem {
40 /// Stable op id index into the dialect registry.
41 pub op_handle: u32,
42 /// Input-buffer handle.
43 pub input_handle: u32,
44 /// Output-buffer handle.
45 pub output_handle: u32,
46 /// Optional per-item parameter word.
47 pub param: u32,
48}
49
50/// Production counters from one megakernel dispatch.
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub struct ResidentQueueTelemetry {
53 /// Bytes uploaded across control, ring, debug, and IO inputs.
54 pub bytes_uploaded: u64,
55 /// Bytes read back across all megakernel output buffers.
56 pub bytes_read_back: u64,
57 /// Total host/device transfer bytes attributable to this dispatch.
58 pub bytes_moved: u64,
59 /// Resident input allocations performed before dispatch.
60 pub resident_allocations: u32,
61 /// Kernel launches issued for this logical dispatch.
62 pub kernel_launches: u32,
63 /// Host-visible synchronization/readback wait points.
64 pub sync_points: u32,
65 /// Approximate lane occupancy in basis points, capped at 10000.
66 pub occupancy_proxy_bps: u16,
67 /// Active queue/frontier density in basis points, capped at 10000.
68 pub frontier_density_bps: u16,
69 /// Number of output buffers read back from the backend.
70 pub readback_buffers: u32,
71 /// True when the direct dispatch reused a compiled megakernel pipeline.
72 pub compiled_pipeline_cache_hit: bool,
73 /// True when the direct dispatch reused resident input resources.
74 pub resident_input_cache_hit: bool,
75 /// Scale-aware topology selected by the launch policy.
76 pub topology: ResidentQueueTopology,
77 /// Queue pressure classification selected by the launch policy.
78 pub pressure: ResidentQueuePressure,
79 /// Interpreter or JIT route selected by launch policy telemetry.
80 pub execution_mode: ResidentExecutionMode,
81 /// Sparse-hit capacity selected by the launch policy.
82 pub hit_capacity: u32,
83 /// Estimated peak device bytes for the selected launch plan.
84 pub estimated_peak_device_bytes: u64,
85 /// Hard device-memory budget applied to the launch. Zero means unbounded.
86 pub device_memory_budget_bytes: u64,
87}
88
89impl Default for ResidentQueueTelemetry {
90 fn default() -> Self {
91 Self {
92 bytes_uploaded: 0,
93 bytes_read_back: 0,
94 bytes_moved: 0,
95 resident_allocations: 0,
96 kernel_launches: 0,
97 sync_points: 0,
98 occupancy_proxy_bps: 0,
99 frontier_density_bps: 0,
100 readback_buffers: 0,
101 compiled_pipeline_cache_hit: false,
102 resident_input_cache_hit: false,
103 topology: ResidentQueueTopology::Empty,
104 pressure: ResidentQueuePressure::Empty,
105 execution_mode: ResidentExecutionMode::Interpreter,
106 hit_capacity: 0,
107 estimated_peak_device_bytes: 0,
108 device_memory_budget_bytes: 0,
109 }
110 }
111}
112
113/// Summary stats from one megakernel run.
114#[derive(Debug, Clone, Default)]
115pub struct ResidentQueueReport {
116 /// Items the workers processed before exiting.
117 pub items_processed: u64,
118 /// Items still queued when `max_wall_time` fired.
119 pub items_remaining: u64,
120 /// Wall-clock time spent.
121 pub wall_time: Duration,
122 /// Host-side time spent shaping the queue before publication:
123 /// dedupe, fusion planning, and launch-geometry preparation.
124 pub queue_plan_ns: u64,
125 /// Host-side time spent encoding protocol buffers and publishing
126 /// queued work into ring slots.
127 pub queue_publish_ns: u64,
128 /// Host-observed backend dispatch latency after queue publication.
129 pub backend_dispatch_ns: u64,
130 /// Host-observed time spent computing optional region lineage after
131 /// dispatch. Zero when lineage tracking is skipped.
132 pub lineage_ns: u64,
133 /// Logical work items removed by queue dedupe before publication.
134 pub deduped_items: u64,
135 /// Work items actually published into megakernel ring slots.
136 pub published_items: u64,
137 /// Number of work items included in region lineage tracking.
138 pub lineage_items: u64,
139 /// Production counters for performance gates and launch tuning.
140 pub telemetry: ResidentQueueTelemetry,
141 /// Per-output provenance lineage bitsets, one entry per fused
142 /// region in dispatch order. `lineage[i]` is a 32-bit set of
143 /// source-rule IDs that contributed to fused-region `i`'s output,
144 /// computed via the substrate
145 /// `vyre_self_substrate::scallop_provenance` Datalog
146 /// closure on the rule-derivation graph. Empty `Vec` when
147 /// provenance tracking was disabled for the dispatch.
148 ///
149 /// Lets observability collectors (Tempo, Honeycomb, Prometheus)
150 /// attribute every megakernel output back to the source rules
151 /// that derived it - without this, fused-region outputs lose
152 /// their lineage.
153 pub region_lineage: Vec<u32>,
154}