Mizan codegen substrate: Rust kernel + Rust codegen binary, JS generator deleted

The Mizan codegen substrate moves off JavaScript template-literal emission
onto a compiled Rust binary that consumes the same OpenAPI + x-mizan-* IR
the JS substrate consumed. Three structural wins fall out of one move:

1. Moat closes. The codegen logic (how `affects` becomes auto-invalidation,
   how named contexts collapse onto bundled fetches, how the registry-to-
   Provider mapping is shaped) ships compiled instead of as source bytes
   in every consumer's node_modules.

2. Pattern F (lines.push append-walls) becomes structurally unauthorable.
   The emit substrate is askama templates in templates/<target>/*.j2 —
   actual target-language files with {{ ... }} substitution markers,
   syntax-highlighted natively, type-checked against the render context
   structs at compile time. The Rust emit modules build typed render
   contexts and call .render(); no string-builder surface exists.

3. OpenAPI `default`-bearing fields now emit as non-optional in TS / Python
   / Rust — the server always populates them, so consumer code reads them
   without nullable checks. Surfaced by Blazr's typecheck on regeneration.

Layout:
  frontends/mizan-rust/        — Rust port of @mizan/base; #[cfg(feature="pyo3")]
                                 exposes PyMizanClient for the Python target.
  protocol/mizan-codegen/      — codegen binary source + askama templates.
  protocol/mizan-generate/     — npm-package shim. bin/launcher.mjs dispatches
                                 to the platform-appropriate prebuilt binary.
                                 Old generator/ JS tree deleted.
  tests/rust/                  — wire-parity drivers. drive_kernel exercises
                                 raw client.call() / fetch_context(); drive_emitted
                                 exercises the typed crate the codegen emits.
  tests/afi/afi_codegen_app.py — codegen entrypoint module (imports + registers).
  backends/mizan-fastapi/.../schema.py — adds outputNullable so the Rust
                                 codegen can wrap T | None responses in Option<T>.

Verification:
  - 20 mizan-codegen tests green (IR deserialization, byte-equivalent
    parity vs JS baseline for stage1/rust/python/react/vue/svelte,
    structural test for channels).
  - tests/rust/run_wire_parity.py — 12/12 probes green via the Rust binary
    driving the FastAPI fixture end-to-end.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

protocol/mizan-codegen/src/config.rs

@@ -0,0 +1,119 @@
+//! Codegen configuration — deserialized from `mizan.toml` at the consumer
+//! project root. Replaces the JS substrate's `mizan.config.mjs`.
+//!
+//! Example:
+//!
+//! ```toml
+//! project_id = "blazr-studio"
+//! output = "src/api"
+//! targets = ["react"]
+//!
+//! [source.fastapi]
+//! module = "blazr_session.handlers"
+//! cwd = "../.."
+//! command = ["uv", "run", "python"]
+//!
+//! [rust_kernel]
+//! path = "../../mizan/frontends/mizan-rust"
+//! ```
+
+use std::collections::BTreeMap;
+use std::path::PathBuf;
+
+use serde::Deserialize;
+
+
+#[derive(Debug, Deserialize)]
+pub struct Config {
+    #[serde(default)]
+    pub project_id: Option<String>,
+
+    #[serde(default = "default_output")]
+    pub output: PathBuf,
+
+    #[serde(default = "default_targets")]
+    pub targets: Vec<String>,
+
+    #[serde(default)]
+    pub source: SourceConfig,
+
+    #[serde(default)]
+    pub rust_kernel: Option<RustKernelSpec>,
+
+    #[serde(default)]
+    pub rust_crate_name: Option<String>,
+}
+
+
+fn default_output() -> PathBuf {
+    PathBuf::from("src/api")
+}
+
+
+fn default_targets() -> Vec<String> {
+    vec!["react".to_string()]
+}
+
+
+#[derive(Debug, Deserialize, Default)]
+pub struct SourceConfig {
+    #[serde(default)]
+    pub fastapi: Option<FastapiSource>,
+
+    #[serde(default)]
+    pub django: Option<DjangoSource>,
+}
+
+
+#[derive(Debug, Deserialize)]
+pub struct FastapiSource {
+    pub module: String,
+
+    #[serde(default)]
+    pub cwd: Option<PathBuf>,
+
+    #[serde(default)]
+    pub python: Option<String>,
+
+    #[serde(default)]
+    pub command: Option<Vec<String>>,
+
+    #[serde(default)]
+    pub env: BTreeMap<String, String>,
+}
+
+
+#[derive(Debug, Deserialize)]
+pub struct DjangoSource {
+    pub manage_path: PathBuf,
+
+    #[serde(default)]
+    pub python: Option<String>,
+
+    #[serde(default)]
+    pub command: Option<Vec<String>>,
+
+    #[serde(default)]
+    pub env: BTreeMap<String, String>,
+}
+
+
+#[derive(Debug, Deserialize, Clone)]
+#[serde(untagged)]
+pub enum RustKernelSpec {
+    Path {
+        path: String,
+    },
+    Git {
+        git: String,
+        #[serde(default)]
+        tag: Option<String>,
+        #[serde(default)]
+        rev: Option<String>,
+        #[serde(default)]
+        branch: Option<String>,
+    },
+    Version {
+        version: String,
+    },
+}

protocol/mizan-codegen/src/emit/casing.rs

@@ -0,0 +1,137 @@
+//! Casing transforms — port of `protocol/mizan-generate/generator/lib/casing.mjs`.
+//!
+//! The Mizan IR uses snake_case names (`user_id`, `update_profile`). Per-target
+//! identifier conventions vary: TypeScript wants `pascalCase`/`camelCase`,
+//! Rust wants `snake_case` (with `r#`-escaping for keywords). These helpers
+//! pin the conversion so emit-targets share one vocabulary.
+
+
+fn split_parts(s: &str) -> Vec<&str> {
+    s.split(|c: char| c == '.' || c == '-' || c == '_')
+        .filter(|p| !p.is_empty())
+        .collect()
+}
+
+
+fn uppercase_first(s: &str) -> String {
+    let mut chars = s.chars();
+    match chars.next() {
+        Some(first) => first.to_uppercase().chain(chars).collect(),
+        None => String::new(),
+    }
+}
+
+
+fn lowercase_first(s: &str) -> String {
+    let mut chars = s.chars();
+    match chars.next() {
+        Some(first) => first.to_lowercase().chain(chars).collect(),
+        None => String::new(),
+    }
+}
+
+
+pub fn pascal_case(s: &str) -> String {
+    split_parts(s).into_iter().map(uppercase_first).collect()
+}
+
+
+pub fn camel_case(s: &str) -> String {
+    let pascal = pascal_case(s);
+    lowercase_first(&pascal)
+}
+
+
+/// Insert underscores at lowercase/digit-to-uppercase boundaries, unify with
+/// the existing `.`/`-`/`_` separators, then lowercase + join.
+pub fn snake_case(s: &str) -> String {
+    let mut with_boundaries = String::with_capacity(s.len() + 4);
+    let mut prev: Option<char> = None;
+    for c in s.chars() {
+        if let Some(p) = prev {
+            if (p.is_ascii_lowercase() || p.is_ascii_digit()) && c.is_ascii_uppercase() {
+                with_boundaries.push('_');
+            }
+        }
+        with_boundaries.push(c);
+        prev = Some(c);
+    }
+    split_parts(&with_boundaries)
+        .into_iter()
+        .map(|p| p.to_ascii_lowercase())
+        .collect::<Vec<_>>()
+        .join("_")
+}
+
+
+/// Rust reserved words that can be escaped via `r#` (excludes `crate`, `self`,
+/// `Self`, `super`, `extern`, which can't be raw-escaped on stable).
+const RUST_RAW_KEYWORDS: &[&str] = &[
+    "as", "break", "const", "continue", "else", "enum", "false", "fn", "for",
+    "if", "impl", "in", "let", "loop", "match", "mod", "move", "mut", "pub",
+    "ref", "return", "static", "struct", "trait", "true", "type", "unsafe",
+    "use", "where", "while", "async", "await", "dyn", "abstract", "become",
+    "box", "do", "final", "macro", "override", "priv", "typeof", "unsized",
+    "virtual", "yield", "try", "union",
+];
+
+const RUST_HARD_RESERVED: &[&str] = &["crate", "self", "Self", "super", "extern"];
+
+
+pub fn rust_ident(name: &str) -> String {
+    let snake = snake_case(name);
+    if RUST_HARD_RESERVED.contains(&snake.as_str()) {
+        format!("{snake}_")
+    } else if RUST_RAW_KEYWORDS.contains(&snake.as_str()) {
+        format!("r#{snake}")
+    } else {
+        snake
+    }
+}
+
+
+pub fn rust_type_ident(name: &str) -> String {
+    let pascal = pascal_case(name);
+    if RUST_HARD_RESERVED.contains(&pascal.as_str()) {
+        format!("{pascal}_")
+    } else if RUST_RAW_KEYWORDS.contains(&pascal.as_str()) {
+        format!("r#{pascal}")
+    } else {
+        pascal
+    }
+}
+
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pascal_case_matches_js_codegen() {
+        assert_eq!(pascal_case("user_profile"), "UserProfile");
+        assert_eq!(pascal_case("find-user"), "FindUser");
+        assert_eq!(pascal_case("api.v1.users"), "ApiV1Users");
+        assert_eq!(pascal_case(""), "");
+    }
+
+    #[test]
+    fn camel_case_matches_js_codegen() {
+        assert_eq!(camel_case("user_profile"), "userProfile");
+        assert_eq!(camel_case("UpdateProfile"), "updateProfile");
+    }
+
+    #[test]
+    fn snake_case_inserts_pascal_boundaries() {
+        assert_eq!(snake_case("UserProfile"), "user_profile");
+        assert_eq!(snake_case("camelCase"), "camel_case");
+        assert_eq!(snake_case("already_snake"), "already_snake");
+        assert_eq!(snake_case("HTTPResponse"), "httpresponse"); // matches JS behavior
+    }
+
+    #[test]
+    fn rust_ident_escapes_keywords() {
+        assert_eq!(rust_ident("type"), "r#type");
+        assert_eq!(rust_ident("normal"), "normal");
+        assert_eq!(rust_ident("self"), "self_");
+    }
+}

protocol/mizan-codegen/src/emit/channels.rs

@@ -0,0 +1,163 @@
+//! Channels target — emits `channels.ts` (typed message envelopes + channel
+//! registry) and `channels.hooks.tsx` (`useXChannel` React hooks) from the
+//! `x-mizan-channels` extension. Django-only feature; the FastAPI backend's
+//! IR carries an empty channels list and this target emits nothing.
+
+use std::path::PathBuf;
+
+use askama::Template;
+use indexmap::IndexMap;
+
+use crate::config::Config;
+use crate::emit::CodegenTarget;
+use crate::emit::EmittedFile;
+use crate::ir::{JsonSchema, MizanChannel, MizanIR};
+
+
+pub struct ChannelsTarget;
+
+
+impl CodegenTarget for ChannelsTarget {
+    fn name(&self) -> &'static str { "channels" }
+
+    fn emit(&self, ir: &MizanIR, _config: &Config) -> Vec<EmittedFile> {
+        if ir.channels.is_empty() {
+            return Vec::new();
+        }
+
+        let schemas_block = emit_channel_schemas(&ir.channels, &ir.components.schemas);
+
+        let types_content = ChannelsTypes {
+            channels: ir.channels.iter().map(ChannelView::from_ir).collect(),
+            schemas_block,
+        }.render().expect("channels.ts renders");
+
+        let mut type_imports: Vec<String> = Vec::new();
+        for ch in &ir.channels {
+            if ch.has_params { if let Some(t) = &ch.params_type { type_imports.push(t.clone()); } }
+            if ch.has_react_message { if let Some(t) = &ch.react_message_type { type_imports.push(t.clone()); } }
+            if ch.has_django_message { if let Some(t) = &ch.django_message_type { type_imports.push(t.clone()); } }
+        }
+
+        let hooks_content = ChannelsHooks {
+            channels: ir.channels.iter().map(ChannelView::from_ir).collect(),
+            type_imports,
+        }.render().expect("channels.hooks.tsx renders");
+
+        vec![
+            EmittedFile::new(PathBuf::from("channels.ts"), types_content),
+            EmittedFile::new(PathBuf::from("channels.hooks.tsx"), hooks_content),
+        ]
+    }
+}
+
+
+#[derive(Template)]
+#[template(path = "channels/channels.ts.j2", escape = "none")]
+struct ChannelsTypes<'a> {
+    channels: Vec<ChannelView<'a>>,
+    schemas_block: String,
+}
+
+
+#[derive(Template)]
+#[template(path = "channels/channels.hooks.tsx.j2", escape = "none")]
+struct ChannelsHooks<'a> {
+    channels: Vec<ChannelView<'a>>,
+    type_imports: Vec<String>,
+}
+
+
+struct ChannelView<'a> {
+    name: &'a str,
+    pascal_name: &'a str,
+    has_params: bool,
+    has_react_message: bool,
+    has_django_message: bool,
+    params_type: String,
+    react_message_type: String,
+    django_message_type: String,
+    params_type_or_record: String,
+    react_msg_type_or_never: String,
+    django_msg_type_or_never: String,
+}
+
+
+impl<'a> ChannelView<'a> {
+    fn from_ir(ch: &'a MizanChannel) -> Self {
+        let params_type = ch.params_type.clone().unwrap_or_default();
+        let react_message_type = ch.react_message_type.clone().unwrap_or_default();
+        let django_message_type = ch.django_message_type.clone().unwrap_or_default();
+
+        Self {
+            name: &ch.name,
+            pascal_name: &ch.pascal_name,
+            has_params: ch.has_params,
+            has_react_message: ch.has_react_message,
+            has_django_message: ch.has_django_message,
+            params_type_or_record: if ch.has_params { params_type.clone() } else { "Record<string, never>".to_string() },
+            react_msg_type_or_never: if ch.has_react_message { react_message_type.clone() } else { "never".to_string() },
+            django_msg_type_or_never: if ch.has_django_message { django_message_type.clone() } else { "never".to_string() },
+            params_type,
+            react_message_type,
+            django_message_type,
+        }
+    }
+}
+
+
+fn emit_channel_schemas(
+    channels: &[MizanChannel],
+    schemas: &IndexMap<String, JsonSchema>,
+) -> String {
+    let mut blocks: Vec<String> = Vec::new();
+    for ch in channels {
+        for ty in [&ch.params_type, &ch.react_message_type, &ch.django_message_type].iter().filter_map(|t| t.as_ref()) {
+            if let Some(schema) = schemas.get(ty) {
+                blocks.push(emit_schema_as_ts(ty, schema));
+            }
+        }
+    }
+    blocks.join("\n\n")
+}
+
+
+fn emit_schema_as_ts(name: &str, schema: &JsonSchema) -> String {
+    if let Some(props) = &schema.properties {
+        let required: std::collections::HashSet<&str> =
+            schema.required.iter().map(String::as_str).collect();
+        let fields = props.iter()
+            .map(|(field_name, field_schema)| {
+                let opt = if required.contains(field_name.as_str()) { "" } else { "?" };
+                let ty = ts_type_expression(field_schema);
+                format!("    {field_name}{opt}: {ty}")
+            })
+            .collect::<Vec<_>>()
+            .join("\n");
+        if fields.is_empty() {
+            format!("export interface {name} {{}}")
+        } else {
+            format!("export interface {name} {{\n{fields}\n}}")
+        }
+    } else {
+        format!("export type {name} = {}", ts_type_expression(schema))
+    }
+}
+
+
+fn ts_type_expression(schema: &JsonSchema) -> String {
+    if let Some(ref_name) = schema.ref_name() {
+        return ref_name.to_string();
+    }
+    match schema.ty.as_deref() {
+        Some("integer") | Some("number") => "number".to_string(),
+        Some("boolean") => "boolean".to_string(),
+        Some("string") => "string".to_string(),
+        Some("array") => {
+            let elem = ts_type_expression(schema.items.as_deref().unwrap_or(&JsonSchema::default()));
+            format!("{elem}[]")
+        }
+        Some("object") => "Record<string, unknown>".to_string(),
+        _ => "unknown".to_string(),
+    }
+}

protocol/mizan-codegen/src/emit/mod.rs

@@ -0,0 +1,67 @@
+//! Emit substrate — per-target codegen lives here.
+//!
+//! Every target implements `CodegenTarget` and returns the same shape:
+//! a `Vec<EmittedFile>`. The dispatcher in `main.rs` iterates one target
+//! per `--target` flag and writes each `EmittedFile` to disk under the
+//! configured output directory.
+//!
+//! Targets land in subsequent phases; Phase 2 establishes the trait so
+//! the dispatch surface is settled before any target's emit logic is
+//! written.
+
+use std::path::PathBuf;
+
+use crate::config::Config;
+use crate::ir::MizanIR;
+
+pub mod casing;
+pub mod channels;
+pub mod python;
+pub mod react;
+pub mod rust;
+pub mod stage1;
+pub mod svelte;
+pub mod vue;
+
+
+pub trait CodegenTarget {
+    /// Stable identifier — matches the `--target` flag value and the
+    /// `targets = [...]` entry in `mizan.toml`.
+    fn name(&self) -> &'static str;
+
+    /// Walk the IR and produce the per-target file set. Each path is
+    /// relative to the consumer's configured `output` directory.
+    fn emit(&self, ir: &MizanIR, config: &Config) -> Vec<EmittedFile>;
+}
+
+
+pub struct EmittedFile {
+    pub rel_path: PathBuf,
+    pub content: String,
+}
+
+
+impl EmittedFile {
+    pub fn new(rel_path: impl Into<PathBuf>, content: impl Into<String>) -> Self {
+        Self {
+            rel_path: rel_path.into(),
+            content: content.into(),
+        }
+    }
+}
+
+
+/// Look up a registered target by name. Returns `None` for unknown
+/// targets so the CLI can warn instead of panicking.
+pub fn target_by_name(name: &str) -> Option<Box<dyn CodegenTarget>> {
+    match name {
+        "stage1" => Some(Box::new(stage1::Stage1)),
+        "rust" => Some(Box::new(rust::RustCrate)),
+        "python" => Some(Box::new(python::PythonClient)),
+        "react" => Some(Box::new(react::ReactAdapter)),
+        "vue" => Some(Box::new(vue::VueAdapter)),
+        "svelte" => Some(Box::new(svelte::SvelteAdapter)),
+        "channels" => Some(Box::new(channels::ChannelsTarget)),
+        _ => None,
+    }
+}

protocol/mizan-codegen/src/emit/python.rs

@@ -0,0 +1,330 @@
+//! Python target — emits a Pydantic-typed client wrapping the PyO3
+//! extension exposed by `mizan-rust`.
+//!
+//! Output shape lives at `templates/python/*.j2`. Per-method bodies are
+//! pre-rendered in Rust before passing into `client.py.j2` so the template
+//! only owns top-level section layout, not Python method-signature details.
+
+use std::path::PathBuf;
+
+use askama::Template;
+use indexmap::IndexMap;
+
+use crate::config::Config;
+use crate::emit::CodegenTarget;
+use crate::emit::EmittedFile;
+use crate::emit::casing::{pascal_case, rust_ident, snake_case};
+use crate::ir::{IsContext, JsonSchema, MizanContext, MizanFunction, MizanIR};
+
+
+pub struct PythonClient;
+
+
+impl CodegenTarget for PythonClient {
+    fn name(&self) -> &'static str { "python" }
+
+    fn emit(&self, ir: &MizanIR, _config: &Config) -> Vec<EmittedFile> {
+        let schemas_block = ir.components.schemas.iter()
+            .map(|(name, schema)| emit_schema_block(name, schema))
+            .collect::<Vec<_>>()
+            .join("\n\n");
+
+        let types_py = TypesTemplate { schemas_block }.render().expect("types.py renders");
+        let client_py = build_client_template(ir).render().expect("client.py renders");
+        let init_py = InitTemplate {}.render().expect("__init__.py renders");
+
+        vec![
+            EmittedFile::new(PathBuf::from("types.py"), types_py),
+            EmittedFile::new(PathBuf::from("client.py"), client_py),
+            EmittedFile::new(PathBuf::from("__init__.py"), init_py),
+        ]
+    }
+}
+
+
+#[derive(Template)]
+#[template(path = "python/__init__.py.j2", escape = "none")]
+struct InitTemplate {}
+
+
+#[derive(Template)]
+#[template(path = "python/types.py.j2", escape = "none")]
+struct TypesTemplate {
+    schemas_block: String,
+}
+
+
+#[derive(Template)]
+#[template(path = "python/client.py.j2", escape = "none")]
+struct ClientTemplate {
+    ctx_methods_block: String,
+    call_methods_block: String,
+    data_classes_block: String,
+}
+
+
+// ─── types.py schema bodies ────────────────────────────────────────────────
+
+
+fn emit_schema_block(raw_name: &str, schema: &JsonSchema) -> String {
+    let name = pascal_case(raw_name);
+
+    if let Some(values) = &schema.r#enum {
+        if schema.ty.as_deref() == Some("string") {
+            let literal = values.iter()
+                .filter_map(|v| v.as_str())
+                .map(|v| format!("\"{v}\""))
+                .collect::<Vec<_>>()
+                .join(", ");
+            return format!("{name} = Literal[{literal}]");
+        }
+    }
+
+    if schema.ty.as_deref() == Some("array") {
+        let elem = py_type_from_schema(schema.items.as_deref().unwrap_or(&JsonSchema::default()));
+        return format!("{name} = list[{elem}]");
+    }
+
+    if schema.ty.as_deref() == Some("object") {
+        if let Some(props) = &schema.properties {
+            return emit_pydantic_class(&name, schema, props);
+        }
+    }
+
+    let ty = py_type_from_schema(schema);
+    format!("{name} = {ty}")
+}
+
+
+fn emit_pydantic_class(
+    name: &str,
+    schema: &JsonSchema,
+    properties: &IndexMap<String, JsonSchema>,
+) -> String {
+    if properties.is_empty() {
+        return format!("class {name}(BaseModel):\n    pass");
+    }
+    let required: std::collections::HashSet<&str> =
+        schema.required.iter().map(String::as_str).collect();
+
+    let field_lines = properties.iter()
+        .map(|(field_raw, field_schema)| {
+            let mut ty = py_type_from_schema(field_schema);
+            let is_required = required.contains(field_raw.as_str())
+                || field_schema.default.is_some();
+            if !is_required {
+                if !ty.ends_with(" | None") {
+                    ty = format!("{ty} | None");
+                }
+                format!("    {}: {ty} = None", rust_ident(field_raw))
+            } else {
+                format!("    {}: {ty}", rust_ident(field_raw))
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    format!("class {name}(BaseModel):\n{field_lines}")
+}
+
+
+fn py_type_from_schema(schema: &JsonSchema) -> String {
+    if let Some(ref_name) = schema.ref_name() {
+        return pascal_case(ref_name);
+    }
+
+    if let Some(any_of) = &schema.any_of {
+        let has_null = any_of.iter().any(|s| s.ty.as_deref() == Some("null"));
+        let non_null: Vec<&JsonSchema> = any_of
+            .iter()
+            .filter(|s| s.ty.as_deref() != Some("null"))
+            .collect();
+        if has_null && non_null.len() == 1 {
+            return format!("{} | None", py_type_from_schema(non_null[0]));
+        }
+    }
+
+    let nullable = schema.nullable;
+    let inner = inner_py_type(schema);
+    if nullable {
+        format!("{inner} | None")
+    } else {
+        inner
+    }
+}
+
+
+fn inner_py_type(schema: &JsonSchema) -> String {
+    if let Some(values) = &schema.r#enum {
+        if schema.ty.as_deref() == Some("string") {
+            let parts = values.iter()
+                .filter_map(|v| v.as_str())
+                .map(|v| format!("\"{v}\""))
+                .collect::<Vec<_>>()
+                .join(", ");
+            return format!("Literal[{parts}]");
+        }
+    }
+    match schema.ty.as_deref() {
+        Some("integer") => "int".to_string(),
+        Some("number") => "float".to_string(),
+        Some("boolean") => "bool".to_string(),
+        Some("string") => "str".to_string(),
+        Some("array") => {
+            let elem = py_type_from_schema(schema.items.as_deref().unwrap_or(&JsonSchema::default()));
+            format!("list[{elem}]")
+        }
+        Some("object") => {
+            if schema.properties.is_some() { "Any".to_string() }
+            else { "dict[str, Any]".to_string() }
+        }
+        _ => "Any".to_string(),
+    }
+}
+
+
+// ─── client.py method blocks ───────────────────────────────────────────────
+
+
+fn build_client_template(ir: &MizanIR) -> ClientTemplate {
+    let ctx_methods_block = ir.contexts.iter()
+        .map(|(ctx_name, ctx_meta)| {
+            let fetch = emit_fetch_method(ctx_name, ctx_meta);
+            let subscribe = emit_subscribe_method(ctx_name, ctx_meta);
+            format!("{fetch}{subscribe}")
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    let call_methods_block = ir.functions.iter()
+        .filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form)
+        .map(emit_call_method)
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    let data_classes_block = ir.contexts.iter()
+        .map(|(ctx_name, _)| {
+            let ctx_fns: Vec<&MizanFunction> = ir.functions.iter()
+                .filter(|f| f.is_context.as_str() == Some(ctx_name))
+                .collect();
+            emit_context_data_class(ctx_name, &ctx_fns)
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    ClientTemplate { ctx_methods_block, call_methods_block, data_classes_block }
+}
+
+
+fn py_arg_type(json_ty: &str) -> &'static str {
+    match json_ty {
+        "integer" => "int",
+        "number" => "float",
+        "boolean" => "bool",
+        _ => "str",
+    }
+}
+
+
+fn emit_fetch_method(ctx_name: &str, ctx_meta: &MizanContext) -> String {
+    let method_name = format!("fetch_{}_context", snake_case(ctx_name));
+    let param_args = ctx_meta.params.iter()
+        .map(|(n, m)| {
+            let ident = rust_ident(n);
+            let ty = py_arg_type(&m.ty);
+            if m.required { format!("{ident}: {ty}") }
+            else { format!("{ident}: {ty} | None = None") }
+        })
+        .collect::<Vec<_>>()
+        .join(", ");
+    let param_dict = if ctx_meta.params.is_empty() {
+        "{}".to_string()
+    } else {
+        let pairs = ctx_meta.params.iter()
+            .map(|(n, _)| format!("\"{n}\": {}", rust_ident(n)))
+            .collect::<Vec<_>>()
+            .join(", ");
+        format!("{{{pairs}}}")
+    };
+    let data_class = format!("{}ContextData", pascal_case(ctx_name));
+    let arg_sig = if param_args.is_empty() { String::new() } else { format!(", {param_args}") };
+
+    format!(
+        "    def {method_name}(self{arg_sig}) -> \"{data_class}\":\n        raw = self._inner.fetch_context(\"{ctx_name}\", {param_dict})\n        return {data_class}(**raw)\n",
+    )
+}
+
+
+fn emit_subscribe_method(ctx_name: &str, ctx_meta: &MizanContext) -> String {
+    let param_args = ctx_meta.params.iter()
+        .map(|(n, m)| {
+            let ident = rust_ident(n);
+            let ty = py_arg_type(&m.ty);
+            if m.required { format!("{ident}: {ty}") }
+            else { format!("{ident}: {ty} | None = None") }
+        })
+        .collect::<Vec<_>>()
+        .join(", ");
+    let param_dict = if ctx_meta.params.is_empty() {
+        "{}".to_string()
+    } else {
+        let pairs = ctx_meta.params.iter()
+            .map(|(n, _)| format!("\"{n}\": {}", rust_ident(n)))
+            .collect::<Vec<_>>()
+            .join(", ");
+        format!("{{{pairs}}}")
+    };
+    let arg_sig = if param_args.is_empty() { String::new() } else { format!(", {param_args}") };
+    let snake = snake_case(ctx_name);
+    let indent_39 = " ".repeat(39);
+
+    format!(
+        "    def subscribe_{snake}_context(self{arg_sig},\n{indent_39}callback: Callable[[dict[str, Any]], None]) -> PyContextSubscription:\n        return self._inner.subscribe_context(\"{ctx_name}\", {param_dict}, callback)\n",
+    )
+}
+
+
+fn emit_call_method(fn_meta: &MizanFunction) -> String {
+    let method_name = format!("call_{}", snake_case(&fn_meta.name));
+    let pascal_output = pascal_case(&fn_meta.output_type);
+
+    let input_arg = if fn_meta.has_input {
+        let it = fn_meta.input_type.as_deref().unwrap_or("");
+        format!(", args: {}", pascal_case(it))
+    } else {
+        String::new()
+    };
+    let args_expr = if fn_meta.has_input { "args.model_dump()" } else { "{}" };
+    let return_type = if fn_meta.output_nullable {
+        format!("{pascal_output} | None")
+    } else {
+        pascal_output.clone()
+    };
+    let decode_expr = if fn_meta.output_nullable {
+        format!("{pascal_output}(**raw) if raw is not None else None")
+    } else {
+        format!("{pascal_output}(**raw)")
+    };
+
+    format!(
+        "    def {method_name}(self{input_arg}) -> {return_type}:\n        raw = self._inner.call(\"{wire}\", {args_expr})\n        return {decode_expr}\n",
+        wire = fn_meta.name,
+    )
+}
+
+
+fn emit_context_data_class(ctx_name: &str, ctx_fns: &[&MizanFunction]) -> String {
+    let class_name = format!("{}ContextData", pascal_case(ctx_name));
+    let field_lines = ctx_fns.iter()
+        .map(|fn_meta| {
+            let pascal_out = pascal_case(&fn_meta.output_type);
+            let ty = if fn_meta.output_nullable { format!("{pascal_out} | None") } else { pascal_out };
+            format!("    {}: {ty}", rust_ident(&fn_meta.name))
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    format!(
+        "class {class_name}(BaseModel):\n    \"\"\"Bundled return of fetch_{snake}_context.\"\"\"\n{field_lines}\n",
+        snake = snake_case(ctx_name),
+    )
+}

protocol/mizan-codegen/src/emit/react.rs

@@ -0,0 +1,142 @@
+//! React target — Stage 2 emit on top of Stage 1. Wraps each registered
+//! context in a React Provider so kernel subscription happens once per
+//! provider mount; consumer hooks read from React Context.
+//!
+//! Output shape lives at `templates/react/react.tsx.j2`.
+
+use std::path::PathBuf;
+
+use askama::Template;
+
+use crate::config::Config;
+use crate::emit::CodegenTarget;
+use crate::emit::EmittedFile;
+use crate::emit::casing::pascal_case;
+use crate::ir::{IsContext, MizanFunction, MizanIR};
+
+
+pub struct ReactAdapter;
+
+
+impl CodegenTarget for ReactAdapter {
+    fn name(&self) -> &'static str { "react" }
+
+    fn emit(&self, ir: &MizanIR, _config: &Config) -> Vec<EmittedFile> {
+        let content = build_template(ir).render().expect("react template renders");
+        vec![EmittedFile::new(PathBuf::from("react.tsx"), content)]
+    }
+}
+
+
+#[derive(Template)]
+#[template(path = "react/react.tsx.j2", escape = "none")]
+struct ReactTemplate<'a> {
+    has_global: bool,
+    stage1_imports: Vec<String>,
+    global_fns: Vec<HookRender<'a>>,
+    named_contexts: Vec<CtxRender<'a>>,
+    calls: Vec<CallRender>,
+}
+
+
+struct HookRender<'a> {
+    pascal: String,
+    output_type: &'a str,
+    name: &'a str,
+}
+
+
+struct CtxRender<'a> {
+    pascal: String,
+    name: &'a str,
+    has_params: bool,
+    fns: Vec<HookRender<'a>>,
+}
+
+
+struct CallRender {
+    pascal: String,
+    has_input: bool,
+}
+
+
+fn dedupe_preserving_order(items: impl IntoIterator<Item = String>) -> Vec<String> {
+    let mut seen = std::collections::HashSet::new();
+    items.into_iter().filter(|s| seen.insert(s.clone())).collect()
+}
+
+
+fn build_template(ir: &MizanIR) -> ReactTemplate<'_> {
+    let has_global = ir.contexts.contains_key("global");
+
+    let global_fns: Vec<HookRender> = ir.functions.iter()
+        .filter(|f| f.is_context.as_str() == Some("global"))
+        .map(|f| HookRender {
+            pascal: pascal_case(&f.camel_name),
+            output_type: &f.output_type,
+            name: &f.name,
+        })
+        .collect();
+
+    let named_contexts: Vec<CtxRender> = ir.contexts.iter()
+        .filter(|(n, _)| n.as_str() != "global")
+        .map(|(ctx_name, ctx_meta)| {
+            let ctx_fns: Vec<HookRender> = ir.functions.iter()
+                .filter(|f| f.is_context.as_str() == Some(ctx_name.as_str()))
+                .map(|f| HookRender {
+                    pascal: pascal_case(&f.camel_name),
+                    output_type: &f.output_type,
+                    name: &f.name,
+                })
+                .collect();
+            CtxRender {
+                pascal: pascal_case(ctx_name),
+                name: ctx_name,
+                has_params: !ctx_meta.params.is_empty(),
+                fns: ctx_fns,
+            }
+        })
+        .collect();
+
+    let mutations: Vec<&MizanFunction> = ir.functions.iter()
+        .filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form && !f.affects.is_empty())
+        .collect();
+    let plain_fns: Vec<&MizanFunction> = ir.functions.iter()
+        .filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form && f.affects.is_empty())
+        .collect();
+
+    let calls: Vec<CallRender> = mutations.iter().chain(plain_fns.iter())
+        .map(|f| CallRender {
+            pascal: pascal_case(&f.camel_name),
+            has_input: f.has_input,
+        })
+        .collect();
+
+    let mut stage1: Vec<String> = Vec::new();
+    for ctx_name in ir.contexts.keys() {
+        let p = pascal_case(ctx_name);
+        stage1.push(format!("fetch{p}Context"));
+        stage1.push(format!("type {p}ContextData"));
+        stage1.push(format!("type {p}ContextParams"));
+    }
+    for fn_meta in mutations.iter().chain(plain_fns.iter()) {
+        stage1.push(format!("call{}", pascal_case(&fn_meta.camel_name)));
+    }
+    let context_fns: Vec<&MizanFunction> = ir.functions.iter()
+        .filter(|f| !matches!(f.is_context, IsContext::No))
+        .collect();
+    let output_types = dedupe_preserving_order(
+        context_fns.iter().map(|f| f.output_type.clone()),
+    );
+    for t in output_types {
+        stage1.push(format!("type {t}"));
+    }
+
+    ReactTemplate {
+        has_global,
+        stage1_imports: stage1,
+        global_fns,
+        named_contexts,
+        calls,
+    }
+}

protocol/mizan-codegen/src/emit/rust.rs

@@ -0,0 +1,474 @@
+//! Rust target — emits a complete Cargo crate consuming the
+//! `mizan-rust` kernel. Output shape lives at `templates/rust/*.j2`.
+
+use std::path::PathBuf;
+
+use askama::Template;
+use indexmap::IndexMap;
+
+use crate::config::{Config, RustKernelSpec};
+use crate::emit::CodegenTarget;
+use crate::emit::EmittedFile;
+use crate::emit::casing::{pascal_case, rust_ident, rust_type_ident, snake_case};
+use crate::ir::{IsContext, JsonSchema, MizanContext, MizanFunction, MizanIR};
+
+
+pub struct RustCrate;
+
+
+impl CodegenTarget for RustCrate {
+    fn name(&self) -> &'static str { "rust" }
+
+    fn emit(&self, ir: &MizanIR, config: &Config) -> Vec<EmittedFile> {
+        let crate_name = config
+            .rust_crate_name
+            .clone()
+            .unwrap_or_else(|| "mizan_client".to_string());
+
+        let kernel_dep = format_kernel_dep(config.rust_kernel.as_ref());
+
+        let mut out: Vec<EmittedFile> = Vec::new();
+
+        out.push(EmittedFile::new(
+            "Cargo.toml",
+            CargoTemplate { crate_name: &crate_name, kernel_dep: &kernel_dep }
+                .render().expect("Cargo.toml renders"),
+        ));
+
+        out.push(EmittedFile::new("src/types.rs", emit_types_rs(&ir.components.schemas)));
+
+        let mut context_modules: Vec<String> = Vec::new();
+        for (ctx_name, ctx_meta) in &ir.contexts {
+            let module_name = snake_case(ctx_name);
+            out.push(EmittedFile::new(
+                PathBuf::from("src/contexts").join(format!("{module_name}.rs")),
+                emit_context_file(ctx_name, ctx_meta, &ir.functions),
+            ));
+            context_modules.push(module_name);
+        }
+        if !context_modules.is_empty() {
+            out.push(EmittedFile::new("src/contexts/mod.rs", emit_mod_file(&context_modules)));
+        }
+
+        let mut mutation_modules: Vec<String> = Vec::new();
+        let mut function_modules: Vec<String> = Vec::new();
+        for fn_meta in &ir.functions {
+            if !matches!(fn_meta.is_context, IsContext::No) || fn_meta.is_form { continue; }
+            let is_mutation = !fn_meta.affects.is_empty();
+            let kind = if is_mutation { "mutations" } else { "functions" };
+            let module_name = snake_case(&fn_meta.camel_name);
+            out.push(EmittedFile::new(
+                PathBuf::from(format!("src/{kind}")).join(format!("{module_name}.rs")),
+                emit_call_file(fn_meta),
+            ));
+            if is_mutation {
+                mutation_modules.push(module_name);
+            } else {
+                function_modules.push(module_name);
+            }
+        }
+        if !mutation_modules.is_empty() {
+            out.push(EmittedFile::new("src/mutations/mod.rs", emit_mod_file(&mutation_modules)));
+        }
+        if !function_modules.is_empty() {
+            out.push(EmittedFile::new("src/functions/mod.rs", emit_mod_file(&function_modules)));
+        }
+
+        out.push(EmittedFile::new(
+            "src/lib.rs",
+            LibTemplate {
+                has_contexts: !context_modules.is_empty(),
+                has_mutations: !mutation_modules.is_empty(),
+                has_functions: !function_modules.is_empty(),
+            }.render().expect("lib.rs renders"),
+        ));
+
+        out
+    }
+}
+
+
+#[derive(Template)]
+#[template(path = "rust/Cargo.toml.j2", escape = "none")]
+struct CargoTemplate<'a> {
+    crate_name: &'a str,
+    kernel_dep: &'a str,
+}
+
+
+#[derive(Template)]
+#[template(path = "rust/lib.rs.j2", escape = "none")]
+struct LibTemplate {
+    has_contexts: bool,
+    has_mutations: bool,
+    has_functions: bool,
+}
+
+
+#[derive(Template)]
+#[template(path = "rust/mod.rs.j2", escape = "none")]
+struct ModTemplate {
+    modules: Vec<String>,
+}
+
+
+#[derive(Template)]
+#[template(path = "rust/context.rs.j2", escape = "none")]
+struct ContextTemplate<'a> {
+    pascal: String,
+    snake: String,
+    ctx_name: &'a str,
+    type_imports: Vec<String>,
+    data_fields: Vec<StructField>,
+    params: Vec<StructField>,
+}
+
+
+#[derive(Template)]
+#[template(path = "rust/call.rs.j2", escape = "none")]
+struct CallTemplate<'a> {
+    snake: String,
+    name: &'a str,
+    return_type: String,
+    type_imports: Vec<String>,
+    input_param: String,
+    args_value: &'static str,
+}
+
+
+#[derive(Template)]
+#[template(path = "rust/types.rs.j2", escape = "none")]
+struct TypesTemplate {
+    schemas_block: String,
+    hoisted_enums_block: String,
+}
+
+
+struct StructField {
+    raw_name: String,
+    ident: String,
+    ty: String,
+    has_rename: bool,
+}
+
+
+fn dedupe_preserving_order(items: impl IntoIterator<Item = String>) -> Vec<String> {
+    let mut seen = std::collections::HashSet::new();
+    items.into_iter().filter(|s| seen.insert(s.clone())).collect()
+}
+
+
+// ─── Cargo.toml ────────────────────────────────────────────────────────────
+
+
+fn format_kernel_dep(spec: Option<&RustKernelSpec>) -> String {
+    match spec {
+        Some(RustKernelSpec::Path { path }) => format!("{{ path = {} }}", json_str(path)),
+        Some(RustKernelSpec::Git { git, tag, rev, branch }) => {
+            let mut parts = vec![format!("git = {}", json_str(git))];
+            if let Some(t) = tag { parts.push(format!("tag = {}", json_str(t))); }
+            if let Some(r) = rev { parts.push(format!("rev = {}", json_str(r))); }
+            if let Some(b) = branch { parts.push(format!("branch = {}", json_str(b))); }
+            format!("{{ {} }}", parts.join(", "))
+        }
+        Some(RustKernelSpec::Version { version }) => format!("{{ version = {} }}", json_str(version)),
+        None => "{ version = \"0.1\" }".to_string(),
+    }
+}
+
+
+fn json_str(s: &str) -> String {
+    serde_json::to_string(s).expect("string literal serializes")
+}
+
+
+// ─── mod.rs ────────────────────────────────────────────────────────────────
+
+
+fn emit_mod_file(module_names: &[String]) -> String {
+    let mut sorted = module_names.to_vec();
+    sorted.sort();
+    ModTemplate { modules: sorted }.render().expect("mod.rs renders")
+}
+
+
+// ─── Context file ──────────────────────────────────────────────────────────
+
+
+fn emit_context_file(
+    ctx_name: &str,
+    ctx_meta: &MizanContext,
+    all_functions: &[MizanFunction],
+) -> String {
+    let pascal = pascal_case(ctx_name);
+    let snake = snake_case(ctx_name);
+
+    let ctx_fns: Vec<&MizanFunction> = all_functions
+        .iter()
+        .filter(|f| f.is_context.as_str() == Some(ctx_name))
+        .collect();
+
+    let type_imports = dedupe_preserving_order(
+        ctx_fns.iter().map(|f| rust_type_ident(&f.output_type)),
+    );
+
+    let data_fields: Vec<StructField> = ctx_fns.iter()
+        .map(|f| {
+            let ident = rust_ident(&f.name);
+            StructField {
+                has_rename: ident != f.name,
+                raw_name: f.name.clone(),
+                ident,
+                ty: rust_type_ident(&f.output_type),
+            }
+        })
+        .collect();
+
+    let params: Vec<StructField> = ctx_meta.params.iter()
+        .map(|(p_name, p_meta)| {
+            let ident = rust_ident(p_name);
+            let base = param_rust_type(&p_meta.ty);
+            let ty = if p_meta.required { base.to_string() } else { format!("Option<{base}>") };
+            StructField {
+                has_rename: ident != *p_name,
+                raw_name: p_name.clone(),
+                ident,
+                ty,
+            }
+        })
+        .collect();
+
+    ContextTemplate {
+        pascal,
+        snake,
+        ctx_name,
+        type_imports,
+        data_fields,
+        params,
+    }.render().expect("context.rs renders")
+}
+
+
+fn param_rust_type(json_ty: &str) -> &'static str {
+    match json_ty {
+        "integer" => "i64",
+        "number" => "f64",
+        "boolean" => "bool",
+        _ => "String",
+    }
+}
+
+
+// ─── Call file ─────────────────────────────────────────────────────────────
+
+
+fn emit_call_file(fn_meta: &MizanFunction) -> String {
+    let output_type = rust_type_ident(&fn_meta.output_type);
+    let return_type = if fn_meta.output_nullable {
+        format!("Option<{output_type}>")
+    } else {
+        output_type.clone()
+    };
+
+    let input_type = fn_meta.input_type.as_deref().map(rust_type_ident);
+
+    let mut used_seed: Vec<String> = vec![output_type.clone()];
+    if let Some(t) = &input_type { used_seed.push(t.clone()); }
+    let type_imports = dedupe_preserving_order(used_seed);
+
+    let (input_param, args_value) = if fn_meta.has_input {
+        let it = input_type.as_deref().unwrap_or("");
+        (
+            format!(", args: &{it}"),
+            "serde_json::to_value(args).unwrap_or(Value::Object(Default::default()))",
+        )
+    } else {
+        (
+            String::new(),
+            "Value::Object(Default::default())",
+        )
+    };
+
+    CallTemplate {
+        snake: snake_case(&fn_meta.name),
+        name: &fn_meta.name,
+        return_type,
+        type_imports,
+        input_param,
+        args_value,
+    }.render().expect("call.rs renders")
+}
+
+
+// ─── types.rs ──────────────────────────────────────────────────────────────
+
+
+struct EnumCtx {
+    hoisted: Vec<(String, Vec<serde_json::Value>)>,
+    depth: usize,
+    enum_name: Option<String>,
+}
+
+
+fn emit_types_rs(schemas: &IndexMap<String, JsonSchema>) -> String {
+    let mut ctx = EnumCtx { hoisted: Vec::new(), depth: 0, enum_name: None };
+
+    let schemas_block = schemas.iter()
+        .map(|(raw_name, schema)| {
+            let name = rust_type_ident(raw_name);
+            if let Some(values) = &schema.r#enum {
+                if schema.ty.as_deref() == Some("string") {
+                    return emit_string_enum(&name, values);
+                }
+            }
+            if schema.ty.as_deref() == Some("array") {
+                return emit_transparent_array(&name, schema, &mut ctx);
+            }
+            if schema.ty.as_deref() == Some("object") {
+                if let Some(props) = &schema.properties {
+                    return emit_struct(&name, schema, props, &mut ctx);
+                }
+            }
+            emit_type_alias(&name, schema, &mut ctx)
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    let hoisted_enums_block = ctx.hoisted.iter()
+        .map(|(n, v)| emit_string_enum(n, v))
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    TypesTemplate { schemas_block, hoisted_enums_block }
+        .render().expect("types.rs renders")
+}
+
+
+fn emit_string_enum(name: &str, variants: &[serde_json::Value]) -> String {
+    let body = variants.iter()
+        .filter_map(|v| v.as_str())
+        .map(|v| {
+            let ident = pascal_case(v);
+            let rename = if ident == v {
+                String::new()
+            } else {
+                format!("    #[serde(rename = {})]\n", json_str(v))
+            };
+            format!("{rename}    {ident},")
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+    format!(
+        "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum {name} {{\n{body}\n}}\n",
+        name = rust_type_ident(name),
+    )
+}
+
+
+fn emit_transparent_array(name: &str, schema: &JsonSchema, ctx: &mut EnumCtx) -> String {
+    ctx.depth = 1;
+    ctx.enum_name = None;
+    let inner = rust_type_from_schema(schema.items.as_deref().unwrap_or(&JsonSchema::default()), ctx);
+    format!(
+        "#[derive(Debug, Clone, Serialize, Deserialize)]\n#[serde(transparent)]\npub struct {name}(pub Vec<{inner}>);\n",
+    )
+}
+
+
+fn emit_struct(
+    name: &str,
+    schema: &JsonSchema,
+    properties: &IndexMap<String, JsonSchema>,
+    ctx: &mut EnumCtx,
+) -> String {
+    let required: std::collections::HashSet<&str> =
+        schema.required.iter().map(String::as_str).collect();
+
+    let fields = properties.iter()
+        .map(|(field_raw, field_schema)| {
+            let field_name = rust_ident(field_raw);
+            ctx.depth = 1;
+            ctx.enum_name = Some(format!("{name}_{}", pascal_case(field_raw)));
+            let mut ty = rust_type_from_schema(field_schema, ctx);
+            let is_required = required.contains(field_raw.as_str())
+                || field_schema.default.is_some();
+            if !is_required && !ty.starts_with("Option<") {
+                ty = format!("Option<{ty}>");
+            }
+            let rename = if field_name == *field_raw {
+                String::new()
+            } else {
+                format!("    #[serde(rename = \"{field_raw}\")]\n")
+            };
+            format!("{rename}    pub {field_name}: {ty},")
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    format!(
+        "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct {name} {{\n{fields}\n}}\n",
+    )
+}
+
+
+fn emit_type_alias(name: &str, schema: &JsonSchema, ctx: &mut EnumCtx) -> String {
+    ctx.depth = 0;
+    ctx.enum_name = Some(name.to_string());
+    let ty = rust_type_from_schema(schema, ctx);
+    format!("pub type {name} = {ty};\n")
+}
+
+
+fn rust_type_from_schema(schema: &JsonSchema, ctx: &mut EnumCtx) -> String {
+    if let Some(r) = schema.ref_name() {
+        return rust_type_ident(r);
+    }
+
+    if let Some(any_of) = &schema.any_of {
+        let has_null = any_of.iter().any(|s| s.ty.as_deref() == Some("null"));
+        let non_null: Vec<&JsonSchema> = any_of
+            .iter()
+            .filter(|s| s.ty.as_deref() != Some("null"))
+            .collect();
+        if has_null && non_null.len() == 1 {
+            ctx.enum_name = None;
+            return format!("Option<{}>", rust_type_from_schema(non_null[0], ctx));
+        }
+    }
+
+    let nullable = schema.nullable;
+    let inner = inner_rust_type(schema, ctx);
+    if nullable {
+        format!("Option<{inner}>")
+    } else {
+        inner
+    }
+}
+
+
+fn inner_rust_type(schema: &JsonSchema, ctx: &mut EnumCtx) -> String {
+    if let Some(values) = &schema.r#enum {
+        if schema.ty.as_deref() == Some("string") {
+            let enum_name = ctx
+                .enum_name
+                .clone()
+                .unwrap_or_else(|| format!("Enum_{}", ctx.depth));
+            ctx.hoisted.push((enum_name.clone(), values.clone()));
+            return enum_name;
+        }
+    }
+    match schema.ty.as_deref() {
+        Some("integer") => "i64".to_string(),
+        Some("number") => "f64".to_string(),
+        Some("boolean") => "bool".to_string(),
+        Some("string") => "String".to_string(),
+        Some("array") => {
+            ctx.depth += 1;
+            ctx.enum_name = None;
+            let inner = rust_type_from_schema(schema.items.as_deref().unwrap_or(&JsonSchema::default()), ctx);
+            format!("Vec<{inner}>")
+        }
+        Some("object") => "serde_json::Value".to_string(),
+        _ => "serde_json::Value".to_string(),
+    }
+}

protocol/mizan-codegen/src/emit/stage1.rs

@@ -0,0 +1,369 @@
+//! Stage 1 — framework-agnostic TypeScript emission.
+//!
+//! Output mirrors `protocol/mizan-generate/generator/lib/stage1.mjs`:
+//!
+//!   types.ts              — typed declarations for every Pydantic model
+//!   contexts/<name>.ts    — `fetch<Name>Context(params)` per context group
+//!   mutations/<name>.ts   — `call<Name>(args)` per mutation
+//!   functions/<name>.ts   — `call<Name>(args)` per plain function
+//!   index.ts              — re-exports
+//!
+//! The deterministic per-function/per-context files match the JS codegen
+//! byte-for-byte against an identical IR; types.ts emits Pydantic schemas
+//! directly as TS interfaces instead of routing through openapi-typescript.
+//! Consumers import by name from index.ts so the structural shape of
+//! types.ts is not load-bearing — only the named exports are.
+
+use std::path::PathBuf;
+
+use askama::Template;
+use indexmap::IndexMap;
+
+use crate::config::Config;
+use crate::ir::{IsContext, JsonSchema, MizanContext, MizanFunction, MizanIR};
+use crate::emit::CodegenTarget;
+use crate::emit::EmittedFile;
+use crate::emit::casing::pascal_case;
+
+
+#[derive(Template)]
+#[template(path = "stage1/call.ts.j2", escape = "none")]
+struct CallTemplate<'a> {
+    pascal: &'a str,
+    name: &'a str,
+    has_input: bool,
+    input_type: &'a str,
+    output_type: &'a str,
+    type_imports: Vec<String>,
+}
+
+
+#[derive(Template)]
+#[template(path = "stage1/context.ts.j2", escape = "none")]
+struct ContextTemplate<'a> {
+    pascal: &'a str,
+    ctx_name: &'a str,
+    type_imports: Vec<String>,
+    data_fields: Vec<ContextDataField<'a>>,
+    has_params: bool,
+    params: Vec<ContextParamField<'a>>,
+}
+
+
+struct ContextDataField<'a> {
+    name: &'a str,
+    output_type: &'a str,
+}
+
+
+struct ContextParamField<'a> {
+    name: &'a str,
+    ts_type: &'static str,
+    required: bool,
+}
+
+
+#[derive(Template)]
+#[template(path = "stage1/index.ts.j2", escape = "none")]
+struct IndexTemplate<'a> {
+    contexts: Vec<IndexContext<'a>>,
+    calls: Vec<IndexCall<'a>>,
+    framework_adapters: Vec<&'static str>,
+}
+
+
+struct IndexContext<'a> {
+    pascal: String,
+    name: &'a str,
+}
+
+
+struct IndexCall<'a> {
+    pascal: String,
+    camel_name: &'a str,
+    dir: &'static str,
+}
+
+
+pub struct Stage1;
+
+
+impl CodegenTarget for Stage1 {
+    fn name(&self) -> &'static str { "stage1" }
+
+    fn emit(&self, ir: &MizanIR, config: &Config) -> Vec<EmittedFile> {
+        let mut out: Vec<EmittedFile> = Vec::new();
+
+        out.push(EmittedFile::new("types.ts", emit_types(&ir.components.schemas)));
+
+        for (ctx_name, ctx_meta) in &ir.contexts {
+            let content = emit_context_file(ctx_name, ctx_meta, &ir.functions);
+            out.push(EmittedFile::new(
+                PathBuf::from("contexts").join(format!("{ctx_name}.ts")),
+                content,
+            ));
+        }
+
+        for fn_meta in regular_functions(&ir.functions) {
+            let dir = if fn_meta.affects.is_empty() { "functions" } else { "mutations" };
+            let content = emit_call_file(fn_meta);
+            out.push(EmittedFile::new(
+                PathBuf::from(dir).join(format!("{}.ts", fn_meta.camel_name)),
+                content,
+            ));
+        }
+
+        out.push(EmittedFile::new("index.ts", emit_stage1_index(ir, config)));
+
+        out
+    }
+}
+
+
+fn regular_functions(functions: &[MizanFunction]) -> impl Iterator<Item = &MizanFunction> {
+    functions.iter().filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form)
+}
+
+
+fn dedupe_preserving_order(items: impl IntoIterator<Item = String>) -> Vec<String> {
+    let mut seen = std::collections::HashSet::new();
+    items.into_iter().filter(|s| seen.insert(s.clone())).collect()
+}
+
+
+// ─── Per-context file ──────────────────────────────────────────────────────
+
+
+fn emit_context_file(
+    ctx_name: &str,
+    ctx_meta: &MizanContext,
+    all_functions: &[MizanFunction],
+) -> String {
+    let pascal = pascal_case(ctx_name);
+    let ctx_fns: Vec<&MizanFunction> = all_functions
+        .iter()
+        .filter(|f| f.is_context.as_str() == Some(ctx_name))
+        .collect();
+
+    let type_imports = dedupe_preserving_order(
+        ctx_fns.iter().map(|f| f.output_type.clone()),
+    );
+
+    let data_fields: Vec<ContextDataField> = ctx_fns
+        .iter()
+        .map(|f| ContextDataField { name: &f.name, output_type: &f.output_type })
+        .collect();
+
+    let params: Vec<ContextParamField> = ctx_meta.params.iter()
+        .map(|(name, meta)| ContextParamField {
+            name,
+            ts_type: json_ty_to_ts(&meta.ty),
+            required: meta.required,
+        })
+        .collect();
+
+    let template = ContextTemplate {
+        pascal: &pascal,
+        ctx_name,
+        type_imports,
+        data_fields,
+        has_params: !ctx_meta.params.is_empty(),
+        params,
+    };
+    template.render().expect("context template renders")
+}
+
+
+fn json_ty_to_ts(json_ty: &str) -> &'static str {
+    match json_ty {
+        "integer" | "number" => "number",
+        "boolean" => "boolean",
+        _ => "string",
+    }
+}
+
+
+// ─── Per-function (call) file — same shape for mutations + plain ──────────
+
+
+fn emit_call_file(fn_meta: &MizanFunction) -> String {
+    let pascal = pascal_case(&fn_meta.camel_name);
+
+    let mut imports: Vec<String> = Vec::new();
+    if fn_meta.has_input {
+        if let Some(t) = &fn_meta.input_type { imports.push(t.clone()); }
+    }
+    imports.push(fn_meta.output_type.clone());
+    let type_imports = dedupe_preserving_order(imports);
+
+    let template = CallTemplate {
+        pascal: &pascal,
+        name: &fn_meta.name,
+        has_input: fn_meta.has_input,
+        input_type: fn_meta.input_type.as_deref().unwrap_or(""),
+        output_type: &fn_meta.output_type,
+        type_imports,
+    };
+    template.render().expect("call template renders")
+}
+
+
+// ─── Stage 1 index ─────────────────────────────────────────────────────────
+
+
+fn emit_stage1_index(ir: &MizanIR, config: &Config) -> String {
+    let contexts: Vec<IndexContext> = ir.contexts.keys()
+        .map(|ctx_name| IndexContext { pascal: pascal_case(ctx_name), name: ctx_name })
+        .collect();
+
+    let calls: Vec<IndexCall> = regular_functions(&ir.functions)
+        .map(|fn_meta| IndexCall {
+            pascal: pascal_case(&fn_meta.camel_name),
+            camel_name: &fn_meta.camel_name,
+            dir: if fn_meta.affects.is_empty() { "functions" } else { "mutations" },
+        })
+        .collect();
+
+    // Stage 2 single-file frontend adapters get re-exported from index.ts so
+    // consumers can `import { MizanContext, useEcho } from './api'`.
+    let framework_adapters: Vec<&'static str> = ["react", "vue", "svelte"].iter()
+        .copied()
+        .filter(|t| config.targets.iter().any(|cfg_t| cfg_t == t))
+        .collect();
+
+    IndexTemplate { contexts, calls, framework_adapters }
+        .render().expect("index template renders")
+}
+
+
+// ─── types.ts ──────────────────────────────────────────────────────────────
+
+
+fn emit_types(schemas: &IndexMap<String, JsonSchema>) -> String {
+    let mut out = String::new();
+    out.push_str("// AUTO-GENERATED by mizan — do not edit\n\n");
+    for (raw_name, schema) in schemas {
+        out.push_str(&emit_schema_decl(raw_name, schema));
+        out.push('\n');
+    }
+    out
+}
+
+
+fn emit_schema_decl(name: &str, schema: &JsonSchema) -> String {
+    // String enum → union of string literals.
+    if let Some(values) = &schema.r#enum {
+        if schema.ty.as_deref() == Some("string") {
+            let union = values
+                .iter()
+                .filter_map(|v| v.as_str())
+                .map(|s| format!("\"{s}\""))
+                .collect::<Vec<_>>()
+                .join(" | ");
+            return format!("export type {name} = {union}\n");
+        }
+    }
+
+    // Top-level array → array alias.
+    if schema.ty.as_deref() == Some("array") {
+        let elem = ts_type_expression(schema.items.as_deref().unwrap_or(&JsonSchema::default()));
+        return format!("export type {name} = {elem}[]\n");
+    }
+
+    // Object with properties → interface declaration.
+    if schema.ty.as_deref() == Some("object") {
+        if let Some(props) = &schema.properties {
+            return emit_interface(name, schema, props);
+        }
+    }
+
+    // Fallback — alias to a structural expression.
+    let expr = ts_type_expression(schema);
+    format!("export type {name} = {expr}\n")
+}
+
+
+fn emit_interface(
+    name: &str,
+    schema: &JsonSchema,
+    properties: &IndexMap<String, JsonSchema>,
+) -> String {
+    let required: std::collections::HashSet<&str> =
+        schema.required.iter().map(String::as_str).collect();
+
+    let fields = properties
+        .iter()
+        .map(|(field_name, field_schema)| {
+            // Fields are non-optional if they're explicitly required OR
+            // if they carry a default value (server always populates).
+            let is_required = required.contains(field_name.as_str())
+                || field_schema.default.is_some();
+            let opt = if is_required { "" } else { "?" };
+            let ty = ts_type_expression(field_schema);
+            format!("    {field_name}{opt}: {ty}")
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    if fields.is_empty() {
+        format!("export interface {name} {{}}\n")
+    } else {
+        format!("export interface {name} {{\n{fields}\n}}\n")
+    }
+}
+
+
+fn ts_type_expression(schema: &JsonSchema) -> String {
+    // `$ref` → bare type name reference into components.schemas.
+    if let Some(ref_name) = schema.ref_name() {
+        return ref_name.to_string();
+    }
+
+    // `anyOf` with a null variant → `T | null`.
+    if let Some(any_of) = &schema.any_of {
+        let has_null = any_of.iter().any(|s| s.ty.as_deref() == Some("null"));
+        let non_null: Vec<&JsonSchema> = any_of
+            .iter()
+            .filter(|s| s.ty.as_deref() != Some("null"))
+            .collect();
+        if has_null && non_null.len() == 1 {
+            return format!("{} | null", ts_type_expression(non_null[0]));
+        }
+        let union = any_of
+            .iter()
+            .map(ts_type_expression)
+            .collect::<Vec<_>>()
+            .join(" | ");
+        return union;
+    }
+
+    if let Some(values) = &schema.r#enum {
+        if schema.ty.as_deref() == Some("string") {
+            return values
+                .iter()
+                .filter_map(|v| v.as_str())
+                .map(|s| format!("\"{s}\""))
+                .collect::<Vec<_>>()
+                .join(" | ");
+        }
+    }
+
+    let base = match schema.ty.as_deref() {
+        Some("integer") | Some("number") => "number".to_string(),
+        Some("boolean") => "boolean".to_string(),
+        Some("string") => "string".to_string(),
+        Some("array") => {
+            let elem = ts_type_expression(schema.items.as_deref().unwrap_or(&JsonSchema::default()));
+            format!("{elem}[]")
+        }
+        Some("object") => "Record<string, unknown>".to_string(),
+        Some("null") => "null".to_string(),
+        _ => "unknown".to_string(),
+    };
+
+    if schema.nullable {
+        format!("{base} | null")
+    } else {
+        base
+    }
+}

protocol/mizan-codegen/src/emit/svelte.rs

@@ -0,0 +1,78 @@
+//! Svelte target — readable store per context, re-export per call.
+//! Output shape lives at `templates/svelte/svelte.ts.j2`.
+
+use std::path::PathBuf;
+
+use askama::Template;
+
+use crate::config::Config;
+use crate::emit::CodegenTarget;
+use crate::emit::EmittedFile;
+use crate::emit::casing::pascal_case;
+use crate::ir::{IsContext, MizanIR};
+
+
+pub struct SvelteAdapter;
+
+
+impl CodegenTarget for SvelteAdapter {
+    fn name(&self) -> &'static str { "svelte" }
+
+    fn emit(&self, ir: &MizanIR, _config: &Config) -> Vec<EmittedFile> {
+        let content = build_template(ir).render().expect("svelte template renders");
+        vec![EmittedFile::new(PathBuf::from("svelte.ts"), content)]
+    }
+}
+
+
+#[derive(Template)]
+#[template(path = "svelte/svelte.ts.j2", escape = "none")]
+struct SvelteTemplate<'a> {
+    stage1_imports: Vec<String>,
+    contexts: Vec<CtxRender<'a>>,
+    call_exports: Vec<String>,
+}
+
+
+struct CtxRender<'a> {
+    pascal: String,
+    name: &'a str,
+    has_params: bool,
+    params_arg: &'static str,
+}
+
+
+fn build_template(ir: &MizanIR) -> SvelteTemplate<'_> {
+    let contexts: Vec<CtxRender> = ir.contexts.iter()
+        .map(|(ctx_name, ctx_meta)| {
+            let has_params = !ctx_meta.params.is_empty();
+            CtxRender {
+                pascal: pascal_case(ctx_name),
+                name: ctx_name,
+                has_params,
+                params_arg: if has_params { "params" } else { "{} as any" },
+            }
+        })
+        .collect();
+
+    let mutations = ir.functions.iter()
+        .filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form && !f.affects.is_empty());
+    let plain_fns = ir.functions.iter()
+        .filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form && f.affects.is_empty());
+    let call_exports: Vec<String> = mutations.chain(plain_fns)
+        .map(|f| pascal_case(&f.camel_name))
+        .collect();
+
+    let mut stage1: Vec<String> = Vec::new();
+    for ctx_name in ir.contexts.keys() {
+        let p = pascal_case(ctx_name);
+        stage1.push(format!("fetch{p}Context"));
+        stage1.push(format!("type {p}ContextData"));
+        stage1.push(format!("type {p}ContextParams"));
+    }
+    for c in &call_exports {
+        stage1.push(format!("call{c}"));
+    }
+
+    SvelteTemplate { stage1_imports: stage1, contexts, call_exports }
+}

protocol/mizan-codegen/src/emit/vue.rs

@@ -0,0 +1,107 @@
+//! Vue target — composable per context + composable per call.
+//! Output shape lives at `templates/vue/vue.ts.j2`.
+
+use std::path::PathBuf;
+
+use askama::Template;
+
+use crate::config::Config;
+use crate::emit::CodegenTarget;
+use crate::emit::EmittedFile;
+use crate::emit::casing::pascal_case;
+use crate::ir::{IsContext, MizanFunction, MizanIR};
+
+
+pub struct VueAdapter;
+
+
+impl CodegenTarget for VueAdapter {
+    fn name(&self) -> &'static str { "vue" }
+
+    fn emit(&self, ir: &MizanIR, _config: &Config) -> Vec<EmittedFile> {
+        let content = build_template(ir).render().expect("vue template renders");
+        vec![EmittedFile::new(PathBuf::from("vue.ts"), content)]
+    }
+}
+
+
+#[derive(Template)]
+#[template(path = "vue/vue.ts.j2", escape = "none")]
+struct VueTemplate<'a> {
+    stage1_imports: Vec<String>,
+    contexts: Vec<CtxRender<'a>>,
+    calls: Vec<CallRender>,
+}
+
+
+struct CtxRender<'a> {
+    pascal: String,
+    name: &'a str,
+    has_params: bool,
+    params_arg: &'static str,
+    fns: Vec<FnRender<'a>>,
+}
+
+
+struct FnRender<'a> {
+    camel_name: &'a str,
+    name: &'a str,
+    output_type: &'a str,
+}
+
+
+struct CallRender {
+    pascal: String,
+    has_input: bool,
+}
+
+
+fn build_template(ir: &MizanIR) -> VueTemplate<'_> {
+    let contexts: Vec<CtxRender> = ir.contexts.iter()
+        .map(|(ctx_name, ctx_meta)| {
+            let has_params = !ctx_meta.params.is_empty();
+            let ctx_fns: Vec<FnRender> = ir.functions.iter()
+                .filter(|f| f.is_context.as_str() == Some(ctx_name.as_str()))
+                .map(|f| FnRender {
+                    camel_name: &f.camel_name,
+                    name: &f.name,
+                    output_type: &f.output_type,
+                })
+                .collect();
+            CtxRender {
+                pascal: pascal_case(ctx_name),
+                name: ctx_name,
+                has_params,
+                params_arg: if has_params { "params" } else { "{} as any" },
+                fns: ctx_fns,
+            }
+        })
+        .collect();
+
+    let mutations: Vec<&MizanFunction> = ir.functions.iter()
+        .filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form && !f.affects.is_empty())
+        .collect();
+    let plain_fns: Vec<&MizanFunction> = ir.functions.iter()
+        .filter(|f| matches!(f.is_context, IsContext::No) && !f.is_form && f.affects.is_empty())
+        .collect();
+
+    let calls: Vec<CallRender> = mutations.iter().chain(plain_fns.iter())
+        .map(|f| CallRender {
+            pascal: pascal_case(&f.camel_name),
+            has_input: f.has_input,
+        })
+        .collect();
+
+    let mut stage1: Vec<String> = Vec::new();
+    for ctx_name in ir.contexts.keys() {
+        let p = pascal_case(ctx_name);
+        stage1.push(format!("fetch{p}Context"));
+        stage1.push(format!("type {p}ContextData"));
+        stage1.push(format!("type {p}ContextParams"));
+    }
+    for fn_meta in mutations.iter().chain(plain_fns.iter()) {
+        stage1.push(format!("call{}", pascal_case(&fn_meta.camel_name)));
+    }
+
+    VueTemplate { stage1_imports: stage1, contexts, calls }
+}

protocol/mizan-codegen/src/fetch.rs

@@ -0,0 +1,149 @@
+//! Schema fetching — spawns the configured backend's schema-export command
+//! and deserializes its stdout into a typed `MizanIR`.
+//!
+//! Two backends recognized today:
+//!   - FastAPI: `python -m mizan_fastapi.cli <module>`
+//!   - Django:  `python manage.py export_mizan_schema --indent 0`
+//!
+//! The fetcher reads stdout, skips any banner text before the first `{`,
+//! and parses the remainder as JSON.
+
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use anyhow::{anyhow, Context, Result};
+
+use crate::config::{Config, DjangoSource, FastapiSource};
+use crate::ir::MizanIR;
+
+
+pub fn fetch_schema(config: &Config, config_dir: &Path) -> Result<MizanIR> {
+    let raw = if let Some(fa) = &config.source.fastapi {
+        run_fastapi(fa, config_dir)?
+    } else if let Some(dj) = &config.source.django {
+        run_django(dj, config_dir)?
+    } else {
+        return Err(anyhow!(
+            "config.source must declare either [source.fastapi] or [source.django]"
+        ));
+    };
+
+    parse_ir(&raw)
+}
+
+
+fn run_fastapi(src: &FastapiSource, config_dir: &Path) -> Result<String> {
+    let cwd = match &src.cwd {
+        Some(rel) => config_dir.join(rel),
+        None => config_dir.to_path_buf(),
+    };
+
+    let (program, mut args) = resolve_command(&src.command, &src.python);
+    args.extend([
+        "-m".to_string(),
+        "mizan_fastapi.cli".to_string(),
+        src.module.clone(),
+    ]);
+
+    run_subprocess(&program, &args, &cwd, &src.env, "FastAPI schema export")
+}
+
+
+fn run_django(src: &DjangoSource, config_dir: &Path) -> Result<String> {
+    let manage_path = config_dir.join(&src.manage_path);
+    let manage_dir = manage_path
+        .parent()
+        .ok_or_else(|| anyhow!("django manage_path has no parent: {}", manage_path.display()))?
+        .to_path_buf();
+
+    let (program, mut args) = resolve_command(&src.command, &src.python);
+
+    // If the user supplied an explicit command (e.g. `uv run python`), they
+    // expect to invoke from the manage_dir without a path prefix on manage.py.
+    // Otherwise we pass the absolute manage_path so the python interpreter
+    // doesn't depend on cwd.
+    if src.command.is_some() {
+        args.push("manage.py".to_string());
+    } else {
+        args.push(manage_path.to_string_lossy().into_owned());
+    }
+    args.extend([
+        "export_mizan_schema".to_string(),
+        "--indent".to_string(),
+        "0".to_string(),
+    ]);
+
+    run_subprocess(&program, &args, &manage_dir, &src.env, "Django schema export")
+}
+
+
+fn resolve_command(
+    explicit: &Option<Vec<String>>,
+    python_override: &Option<String>,
+) -> (String, Vec<String>) {
+    if let Some(cmd) = explicit {
+        let (head, tail) = cmd.split_first().expect("command must be non-empty");
+        return (head.clone(), tail.to_vec());
+    }
+    let python = python_override.as_deref().unwrap_or("python");
+    (python.to_string(), Vec::new())
+}
+
+
+fn run_subprocess(
+    program: &str,
+    args: &[String],
+    cwd: &Path,
+    env: &std::collections::BTreeMap<String, String>,
+    label: &str,
+) -> Result<String> {
+    let mut cmd = Command::new(program);
+    cmd.args(args).current_dir(cwd);
+    for (k, v) in env {
+        cmd.env(k, v);
+    }
+
+    let output = cmd
+        .output()
+        .with_context(|| format!("spawning {label} ({program})"))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        return Err(anyhow!(
+            "{label} failed (exit {:?})\n--- stderr ---\n{stderr}\n--- stdout ---\n{stdout}",
+            output.status.code(),
+        ));
+    }
+
+    let stdout = String::from_utf8(output.stdout)
+        .with_context(|| format!("{label}: non-UTF-8 stdout"))?;
+    Ok(stdout)
+}
+
+
+fn parse_ir(raw: &str) -> Result<MizanIR> {
+    let json_start = raw
+        .find('{')
+        .ok_or_else(|| anyhow!("no JSON object found in schema-export output"))?;
+    serde_json::from_str(&raw[json_start..]).context("deserializing Mizan IR from schema JSON")
+}
+
+
+/// Library helper for tests: deserialize an IR from a pre-fetched JSON string
+/// (no subprocess). Mirrors `parse_ir` but exposed for crate-external callers.
+pub fn parse_ir_from_str(json: &str) -> Result<MizanIR> {
+    parse_ir(json)
+}
+
+
+/// Library helper: resolve a path relative to the config directory, returning
+/// an absolute path. Consumers may want this when constructing output paths.
+pub fn resolve_path(config_dir: &Path, p: impl Into<PathBuf>) -> PathBuf {
+    let p = p.into();
+    if p.is_absolute() {
+        p
+    } else {
+        config_dir.join(p)
+    }
+}

protocol/mizan-codegen/src/ir.rs

@@ -0,0 +1,248 @@
+//! Mizan IR — strongly-typed deserialization of the backends' schema export.
+//!
+//! Every Mizan backend (Django, FastAPI, mizan-ts) emits the same OpenAPI
+//! document with three load-bearing extension fields:
+//!   - `x-mizan-functions`   — array of function entries
+//!   - `x-mizan-contexts`    — map of context groups
+//!   - `components.schemas`  — OpenAPI Pydantic→JSONSchema per Input/Output
+//!
+//! The structs here deserialize that JSON envelope into typed Rust values
+//! the emit targets walk. The OpenAPI document body (paths, info, etc.) is
+//! intentionally not modeled — the codegen consumes only the extensions.
+
+use std::collections::BTreeMap;
+
+use indexmap::IndexMap;
+use serde::Deserialize;
+
+
+#[derive(Debug, Deserialize)]
+pub struct MizanIR {
+    #[serde(rename = "x-mizan-functions", default)]
+    pub functions: Vec<MizanFunction>,
+
+    #[serde(rename = "x-mizan-contexts", default)]
+    pub contexts: IndexMap<String, MizanContext>,
+
+    /// Django-only channel registrations. FastAPI backends emit an empty list.
+    #[serde(rename = "x-mizan-channels", default)]
+    pub channels: Vec<MizanChannel>,
+
+    #[serde(default)]
+    pub components: Components,
+}
+
+
+#[derive(Debug, Deserialize, Clone)]
+pub struct MizanChannel {
+    pub name: String,
+    #[serde(rename = "pascalName")]
+    pub pascal_name: String,
+    #[serde(rename = "hasParams", default)]
+    pub has_params: bool,
+    #[serde(rename = "hasReactMessage", default)]
+    pub has_react_message: bool,
+    #[serde(rename = "hasDjangoMessage", default)]
+    pub has_django_message: bool,
+    #[serde(rename = "paramsType", default)]
+    pub params_type: Option<String>,
+    #[serde(rename = "reactMessageType", default)]
+    pub react_message_type: Option<String>,
+    #[serde(rename = "djangoMessageType", default)]
+    pub django_message_type: Option<String>,
+}
+
+
+#[derive(Debug, Deserialize, Clone)]
+pub struct MizanFunction {
+    pub name: String,
+
+    #[serde(rename = "camelName")]
+    pub camel_name: String,
+
+    #[serde(rename = "hasInput")]
+    pub has_input: bool,
+
+    #[serde(rename = "inputType")]
+    pub input_type: Option<String>,
+
+    #[serde(rename = "outputType")]
+    pub output_type: String,
+
+    #[serde(rename = "outputNullable", default)]
+    pub output_nullable: bool,
+
+    pub transport: Transport,
+
+    #[serde(rename = "isContext", default)]
+    pub is_context: IsContext,
+
+    #[serde(rename = "isForm", default)]
+    pub is_form: bool,
+
+    #[serde(rename = "formName", default)]
+    pub form_name: Option<String>,
+
+    #[serde(rename = "formRole", default)]
+    pub form_role: Option<String>,
+
+    #[serde(default)]
+    pub affects: Vec<AffectTarget>,
+
+    /// Names of contexts whose state is patched by this function's return
+    /// body via the kernel's `splice_slot` merger. Empty when the function
+    /// is not a merge target.
+    #[serde(default)]
+    pub merge: Vec<String>,
+}
+
+
+#[derive(Debug, Deserialize, Default, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Transport {
+    #[default]
+    Http,
+    Websocket,
+    Both,
+}
+
+
+/// IR-level `isContext` value. The backends emit `false` for non-context
+/// functions and a string (`"global"`, `"user"`, …) for context-grouped
+/// functions. Custom Deserialize bridges the boolean/string union into a
+/// typed Rust enum.
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
+pub enum IsContext {
+    #[default]
+    No,
+    Yes(String),
+}
+
+impl IsContext {
+    pub fn as_str(&self) -> Option<&str> {
+        match self {
+            IsContext::No => None,
+            IsContext::Yes(s) => Some(s.as_str()),
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for IsContext {
+    fn deserialize<D>(de: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let v = serde_json::Value::deserialize(de)?;
+        match v {
+            serde_json::Value::Bool(false) => Ok(IsContext::No),
+            serde_json::Value::Bool(true) => Err(serde::de::Error::custom(
+                "isContext: bare `true` is not a valid context name",
+            )),
+            serde_json::Value::String(s) => Ok(IsContext::Yes(s)),
+            serde_json::Value::Null => Ok(IsContext::No),
+            other => Err(serde::de::Error::custom(format!(
+                "isContext: expected `false` or string, got {other:?}"
+            ))),
+        }
+    }
+}
+
+
+#[derive(Debug, Deserialize, Clone)]
+pub struct AffectTarget {
+    #[serde(rename = "type")]
+    pub kind: AffectKind,
+    pub name: String,
+    #[serde(default)]
+    pub context: Option<String>,
+}
+
+
+#[derive(Debug, Deserialize, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum AffectKind {
+    Context,
+    Function,
+}
+
+
+#[derive(Debug, Deserialize, Default, Clone)]
+pub struct MizanContext {
+    #[serde(default)]
+    pub functions: Vec<String>,
+    #[serde(default)]
+    pub params: IndexMap<String, ContextParam>,
+}
+
+
+#[derive(Debug, Deserialize, Clone)]
+pub struct ContextParam {
+    #[serde(rename = "type")]
+    pub ty: String,
+
+    pub required: bool,
+
+    #[serde(rename = "sharedBy", default)]
+    pub shared_by: Vec<String>,
+}
+
+
+#[derive(Debug, Deserialize, Default)]
+pub struct Components {
+    #[serde(default)]
+    pub schemas: IndexMap<String, JsonSchema>,
+}
+
+
+/// JSON Schema subset used by the emit targets. Mirrors the surface the
+/// existing JS adapters traverse (`$ref`, `anyOf`, `enum`, `type`, `items`,
+/// `properties`, `required`, `nullable`). Unknown fields are stashed in
+/// `extra` so backends can include schema annotations the codegen ignores.
+#[derive(Debug, Deserialize, Default, Clone)]
+pub struct JsonSchema {
+    #[serde(rename = "type", default)]
+    pub ty: Option<String>,
+
+    #[serde(rename = "$ref", default)]
+    pub r#ref: Option<String>,
+
+    #[serde(rename = "enum", default)]
+    pub r#enum: Option<Vec<serde_json::Value>>,
+
+    #[serde(rename = "anyOf", default)]
+    pub any_of: Option<Vec<JsonSchema>>,
+
+    #[serde(default)]
+    pub nullable: bool,
+
+    #[serde(default)]
+    pub items: Option<Box<JsonSchema>>,
+
+    #[serde(default)]
+    pub properties: Option<IndexMap<String, JsonSchema>>,
+
+    #[serde(default)]
+    pub required: Vec<String>,
+
+    #[serde(rename = "additionalProperties", default)]
+    pub additional_properties: Option<serde_json::Value>,
+
+    /// Presence of this field means the schema has a default — the server
+    /// always populates it. Consumers can treat the field as non-optional
+    /// even if it's absent from `required`.
+    #[serde(default)]
+    pub default: Option<serde_json::Value>,
+
+    #[serde(flatten)]
+    pub extra: BTreeMap<String, serde_json::Value>,
+}
+
+
+impl JsonSchema {
+    /// `$ref: "#/components/schemas/Foo"` → `Some("Foo")`.
+    pub fn ref_name(&self) -> Option<&str> {
+        self.r#ref
+            .as_deref()
+            .and_then(|s| s.strip_prefix("#/components/schemas/"))
+    }
+}

protocol/mizan-codegen/src/lib.rs

@@ -0,0 +1,10 @@
+//! Mizan codegen — library surface for tests and tooling.
+//!
+//! The binary `mizan-generate` (src/main.rs) is the consumer entry point;
+//! the library re-exports IR / config / fetch / emit so integration tests
+//! can drive the substrate without spawning the binary.
+
+pub mod config;
+pub mod emit;
+pub mod fetch;
+pub mod ir;

protocol/mizan-codegen/src/main.rs

@@ -0,0 +1,164 @@
+//! `mizan-generate` — Rust codegen binary.
+//!
+//! Replaces the Node-based `protocol/mizan-generate/generator/cli.mjs`.
+//! Reads `mizan.toml`, spawns the configured backend to fetch the IR, and
+//! dispatches each `--target` to its `CodegenTarget` impl. Per-target file
+//! emission writes under the configured `output` directory.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+use clap::Parser;
+
+use mizan_codegen::{config, emit, fetch};
+
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "mizan-generate",
+    about = "Mizan code generator — consumes Mizan IR; emits typed clients.",
+)]
+struct Cli {
+    /// Path to the codegen config file.
+    #[arg(short, long, default_value = "mizan.toml")]
+    config: PathBuf,
+
+    /// Output directory (overrides `output` in config).
+    #[arg(short, long)]
+    output: Option<PathBuf>,
+
+    /// Comma-separated list of targets (overrides `targets` in config).
+    #[arg(short, long)]
+    target: Option<String>,
+
+    /// Read the IR from a JSON file instead of spawning the backend's
+    /// schema-export command. The fixture path used by integration tests.
+    #[arg(long)]
+    from_json: Option<PathBuf>,
+}
+
+
+fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    let config_exists = cli.config.exists();
+    let mut config: config::Config = if config_exists {
+        let config_text = fs::read_to_string(&cli.config)
+            .with_context(|| format!("reading config: {}", cli.config.display()))?;
+        toml::from_str(&config_text)
+            .with_context(|| format!("parsing TOML: {}", cli.config.display()))?
+    } else if cli.from_json.is_some() {
+        // --from-json bypasses the fetcher, so a missing config is fine —
+        // CLI flags supply output + targets.
+        config::Config {
+            project_id: None,
+            output: PathBuf::from("."),
+            targets: vec![],
+            source: Default::default(),
+            rust_kernel: None,
+            rust_crate_name: None,
+        }
+    } else {
+        return Err(anyhow::anyhow!(
+            "config not found: {} (pass --from-json to skip fetch)",
+            cli.config.display(),
+        ));
+    };
+
+    if let Some(o) = cli.output {
+        config.output = o;
+    }
+    if let Some(t) = cli.target {
+        config.targets = t.split(',').map(|s| s.trim().to_string()).collect();
+    }
+
+    let config_dir = if config_exists {
+        resolve_config_dir(&cli.config)?
+    } else {
+        std::env::current_dir()?
+    };
+
+    let ir = if let Some(json_path) = &cli.from_json {
+        let abs = if json_path.is_absolute() {
+            json_path.clone()
+        } else {
+            config_dir.join(json_path)
+        };
+        eprintln!("[mizan] Reading IR from {}", abs.display());
+        let raw = fs::read_to_string(&abs)
+            .with_context(|| format!("read {}", abs.display()))?;
+        fetch::parse_ir_from_str(&raw)?
+    } else {
+        eprintln!("[mizan] Fetching schema...");
+        fetch::fetch_schema(&config, &config_dir)?
+    };
+
+    eprintln!(
+        "[mizan] Loaded {} function(s), {} context group(s), {} schema(s)",
+        ir.functions.len(),
+        ir.contexts.len(),
+        ir.components.schemas.len(),
+    );
+
+    // Stage 1 is the framework-agnostic foundation that react/vue/svelte
+    // import from. Auto-include it whenever any consumer of `./index`
+    // (the Stage 1 re-export root) is in the target set.
+    let needs_stage1 = config.targets.iter()
+        .any(|t| matches!(t.as_str(), "react" | "vue" | "svelte"));
+    if needs_stage1 && !config.targets.iter().any(|t| t == "stage1") {
+        config.targets.insert(0, "stage1".to_string());
+    }
+    // Channels schema piggybacks on the main schema (x-mizan-channels);
+    // auto-include the channels emit when react is the target and the
+    // schema actually carries channels.
+    if config.targets.iter().any(|t| t == "react")
+        && !ir.channels.is_empty()
+        && !config.targets.iter().any(|t| t == "channels")
+    {
+        config.targets.push("channels".to_string());
+    }
+
+    eprintln!("[mizan] Targets: {}", config.targets.join(", "));
+
+    let output_dir = if config.output.is_absolute() {
+        config.output.clone()
+    } else {
+        config_dir.join(&config.output)
+    };
+
+    for target_name in &config.targets {
+        let Some(target) = emit::target_by_name(target_name) else {
+            eprintln!("[mizan] WARN: target '{target_name}' has no emitter yet (Phase 2 scaffold)");
+            continue;
+        };
+        let files = target.emit(&ir, &config);
+        for file in files {
+            let path = output_dir.join(&file.rel_path);
+            write_output(&path, &file.content)?;
+            eprintln!("[mizan] {} -> {}", target.name(), file.rel_path.display());
+        }
+    }
+
+    eprintln!("[mizan] Generation complete.");
+    Ok(())
+}
+
+
+fn resolve_config_dir(config_path: &Path) -> Result<PathBuf> {
+    let abs = fs::canonicalize(config_path)
+        .with_context(|| format!("canonicalize {}", config_path.display()))?;
+    Ok(abs
+        .parent()
+        .map(|p| p.to_path_buf())
+        .unwrap_or_else(|| PathBuf::from(".")))
+}
+
+
+fn write_output(path: &Path, content: &str) -> Result<()> {
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("mkdir {}", parent.display()))?;
+    }
+    fs::write(path, content).with_context(|| format!("write {}", path.display()))
+}