refactor(mir): phase260 p0 edge-args plumbing (strangler) + ssot api + docs

src/mir/builder/control_flow/joinir/api/entry.rs

@@ -0,0 +1,14 @@
+//! Entry function helpers (SSOT)
+
+use crate::mir::join_ir::{JoinFunction, JoinModule};
+
+/// Extract entry function from JoinModule (SSOT).
+///
+/// Priority: `join_module.entry` → fallback to `"main"`.
+pub(in crate::mir::builder) fn get_entry_function<'a>(
+    join_module: &'a JoinModule,
+    context: &str,
+) -> Result<&'a JoinFunction, String> {
+    // Re-exported from patterns/common as the SSOT entry point.
+    super::super::patterns::common::get_entry_function(join_module, context)
+}

src/mir/builder/control_flow/joinir/api/mod.rs

@@ -0,0 +1,14 @@
+//! JoinIR integration API (SSOT entry points)
+//!
+//! Purpose: provide a small, stable surface for pattern lowerers and merge code.
+//! This reduces "where should I call this from?" drift and avoids re-implementing
+//! contract logic (SSOT, fail-fast checks) in each pattern.
+//!
+//! Policy:
+//! - Prefer SSOT helpers over ad-hoc logic in patterns.
+//! - Avoid guessing (order/layout/name) in callers; callers pass explicit intent.
+//! - Keep this module thin: mostly wrappers/re-exports with clear naming.
+
+pub(in crate::mir::builder) mod entry;
+pub(in crate::mir::builder) mod pipeline_contracts;
+pub(in crate::mir::builder) mod receiver;

src/mir/builder/control_flow/joinir/api/pipeline_contracts.rs

@@ -0,0 +1,16 @@
+//! Pipeline contract helpers (SSOT)
+
+use crate::mir::join_ir::lowering::inline_boundary::JoinInlineBoundary;
+use crate::mir::join_ir::JoinModule;
+
+/// Run all JoinIR pipeline contract checks (SSOT).
+///
+/// This is the preferred entry point for patterns that need to validate boundary
+/// assumptions before bridge/merge.
+pub(in crate::mir::builder) fn run_all_pipeline_checks(
+    join_module: &JoinModule,
+    boundary: &JoinInlineBoundary,
+) -> Result<(), String> {
+    super::super::merge::contract_checks::run_all_pipeline_checks(join_module, boundary)
+}
+

src/mir/builder/control_flow/joinir/api/receiver.rs

@@ -0,0 +1,20 @@
+//! Receiver helpers (SSOT)
+//!
+//! Motivation: surface syntax uses `this` / `me`, but the MIR builder's `variable_map`
+//! registers the receiver under a specific key. Patterns must not guess that key.
+
+use crate::mir::builder::MirBuilder;
+use crate::mir::ValueId;
+
+/// Return the host ValueId for `me` receiver (SSOT).
+///
+/// Patterns should use this instead of hardcoding `"me"` / `"this"`.
+pub(in crate::mir::builder) fn get_me_host_id(builder: &MirBuilder, context: &str) -> Result<ValueId, String> {
+    builder
+        .variable_ctx
+        .variable_map
+        .get("me")
+        .copied()
+        .ok_or_else(|| format!("[{}] receiver 'me' not found in variable_map", context))
+}
+