From 486adfbec5b6fa73aac00ebea94adb4bd0cd8b81 Mon Sep 17 00:00:00 2001
From: Selfhosting Dev <selfhost@example.invalid>
Date: Sat, 20 Sep 2025 02:08:52 +0900
Subject: [PATCH] mir(hints): add no-op hint types and sink; expose module
 (scaffold, zero-cost)

---
 src/mir/hints.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++
 src/mir/mod.rs   |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 src/mir/hints.rs

diff --git a/src/mir/hints.rs b/src/mir/hints.rs
new file mode 100644
index 00000000..299e5da7
--- /dev/null
+++ b/src/mir/hints.rs
@@ -0,0 +1,44 @@
+#![allow(dead_code)]
+//! MIR Hints — zero-cost structural guidance (scaffold)
+//!
+//! Hints guide lowering/verification without affecting semantics.
+//! They must be stripped before final IR emission.
+
+/// Lightweight set of hint kinds (scaffold).
+#[derive(Debug, Clone)]
+pub enum HintKind {
+    ScopeEnter(u32),
+    ScopeLeave(u32),
+    Defer(Vec<String>),
+    JoinResult(String),
+    LoopCarrier(Vec<String>),
+    LoopHeader,
+    LoopLatch,
+    NoEmptyPhi,
+}
+
+/// Hint sink (no-op). Backends/resolvers may hook into this later.
+#[derive(Default)]
+pub struct HintSink {
+    enabled: bool,
+}
+
+impl HintSink {
+    pub fn new() -> Self { Self { enabled: false } }
+    pub fn with_enabled(mut self, enabled: bool) -> Self { self.enabled = enabled; self }
+
+    #[inline] pub fn record(&mut self, _hint: HintKind) {}
+    #[inline] pub fn scope_enter(&mut self, id: u32) { self.record(HintKind::ScopeEnter(id)); }
+    #[inline] pub fn scope_leave(&mut self, id: u32) { self.record(HintKind::ScopeLeave(id)); }
+    #[inline] pub fn defer_calls<S: Into<String>>(&mut self, calls: impl IntoIterator<Item = S>) {
+        self.record(HintKind::Defer(calls.into_iter().map(|s| s.into()).collect()))
+    }
+    #[inline] pub fn join_result<S: Into<String>>(&mut self, var: S) { self.record(HintKind::JoinResult(var.into())); }
+    #[inline] pub fn loop_carrier<S: Into<String>>(&mut self, vars: impl IntoIterator<Item = S>) {
+        self.record(HintKind::LoopCarrier(vars.into_iter().map(|s| s.into()).collect()))
+    }
+    #[inline] pub fn loop_header(&mut self) { self.record(HintKind::LoopHeader); }
+    #[inline] pub fn loop_latch(&mut self) { self.record(HintKind::LoopLatch); }
+    #[inline] pub fn no_empty_phi(&mut self) { self.record(HintKind::NoEmptyPhi); }
+}
+
diff --git a/src/mir/mod.rs b/src/mir/mod.rs
index 3ec82f26..761daf64 100644
--- a/src/mir/mod.rs
+++ b/src/mir/mod.rs
@@ -21,6 +21,7 @@ pub mod optimizer_passes; // optimizer passes (normalize/diagnostics)
 pub mod optimizer_stats; // extracted stats struct
 pub mod passes;
 pub mod printer;
+pub mod hints; // scaffold: zero-cost guidance (no-op)
 pub mod slot_registry; // Phase 9.79b.1: method slot resolution (IDs)
 pub mod value_id;
 pub mod verification;