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/templates/channels/channels.hooks.tsx.j2

@@ -0,0 +1,26 @@
+'use client'
+
+// AUTO-GENERATED by mizan — do not edit
+
+import { useChannel, type ChannelSubscription } from 'mizan/channels'
+
+{% if !type_imports.is_empty() -%}
+import type { {{ type_imports|join(", ") }} } from './channels'
+
+{% endif -%}
+// ── Channel Hooks ─────────────────────────────────────────────────────────
+
+{% for ch in channels -%}
+/**
+ * Hook for the {{ ch.name }} channel.
+ */
+{% if ch.has_params -%}
+export function use{{ ch.pascal_name }}Channel(params: {{ ch.params_type_or_record }}): ChannelSubscription<{{ ch.params_type_or_record }}, {{ ch.django_msg_type_or_never }}, {{ ch.react_msg_type_or_never }}> {
+    return useChannel('{{ ch.name }}', params)
+}
+{% else -%}
+export function use{{ ch.pascal_name }}Channel(): ChannelSubscription<Record<string, never>, {{ ch.django_msg_type_or_never }}, {{ ch.react_msg_type_or_never }}> {
+    return useChannel('{{ ch.name }}', {})
+}
+{% endif %}
+{% endfor -%}

protocol/mizan-codegen/templates/channels/channels.ts.j2

@@ -0,0 +1,26 @@
+// AUTO-GENERATED by mizan — do not edit
+
+{{ schemas_block }}
+// ── Channel Registry ──────────────────────────────────────────────────────
+
+export const CHANNELS = {
+{%- for ch in channels %}
+    {{ ch.name }}: {
+        name: '{{ ch.name }}',
+        pascalName: '{{ ch.pascal_name }}',
+        hasParams: {{ ch.has_params }},
+        hasReactMessage: {{ ch.has_react_message }},
+        hasDjangoMessage: {{ ch.has_django_message }},
+{%- if ch.has_params %}
+        paramsType: '{{ ch.params_type }}',
+{%- endif %}
+{%- if ch.has_react_message %}
+        reactMessageType: '{{ ch.react_message_type }}',
+{%- endif %}
+{%- if ch.has_django_message %}
+        djangoMessageType: '{{ ch.django_message_type }}',
+{%- endif %}
+    },
+{%- endfor %}
+} as const
+

protocol/mizan-codegen/templates/python/__init__.py.j2

@@ -0,0 +1,5 @@
+# AUTO-GENERATED by mizan — do not edit
+
+from .client import MizanClient  # noqa: F401
+from .types import *  # noqa: F401, F403
+

protocol/mizan-codegen/templates/python/client.py.j2

@@ -0,0 +1,39 @@
+# AUTO-GENERATED by mizan — do not edit
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+# Built from frontends/mizan-rust with `maturin develop --features pyo3`.
+from mizan_rust import PyMizanClient, PyContextSubscription
+
+from .types import *  # noqa: F401, F403
+from .types import BaseModel  # re-import for the synthesized ContextData classes
+
+
+class MizanClient:
+    """Typed Python facade over the PyO3 mizan-rust kernel."""
+
+    def __init__(self, base_url: str, *, session: bool = False,
+                 csrf_cookie_name: str = "csrftoken",
+                 csrf_header_name: str = "X-CSRFToken") -> None:
+        self._inner = PyMizanClient(
+            base_url,
+            session=session,
+            csrf_cookie_name=csrf_cookie_name,
+            csrf_header_name=csrf_header_name,
+        )
+
+{{ ctx_methods_block }}
+{{ call_methods_block }}
+    def invalidate(self, context: str) -> None:
+        self._inner.invalidate(context)
+
+    def invalidate_scoped(self, context: str, params: dict[str, Any]) -> None:
+        self._inner.invalidate_scoped(context, params)
+
+
+# ── Context data shapes (per-context bundle) ──────────────────────────────
+
+{{ data_classes_block }}

protocol/mizan-codegen/templates/python/types.py.j2

@@ -0,0 +1,10 @@
+# AUTO-GENERATED by mizan — do not edit
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+{{ schemas_block }}
+

protocol/mizan-codegen/templates/react/react.tsx.j2

@@ -0,0 +1,180 @@
+'use client'
+
+// AUTO-GENERATED by mizan — do not edit
+
+import {
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useRef,
+    useState,
+    useSyncExternalStore,
+    type ReactNode,
+} from 'react'
+import {
+    configure,
+    initSession,
+    mizanCall,
+    mizanFetch,
+    MizanError,
+    registerContext,
+    type ContextState,
+} from '@mizan/base'
+
+{% if !stage1_imports.is_empty() -%}
+import { {{ stage1_imports|join(", ") }} } from './index'
+
+{% endif -%}
+// Internal — runs inside a Provider, registers with the kernel exactly once.
+function useContextSubscription<T>(
+    name: string,
+    params: Record<string, any>,
+    fetchFn: () => Promise<T>,
+    initialData?: T,
+): ContextState<T> {
+    const ref = useRef<ReturnType<typeof registerContext> | null>(null)
+    if (!ref.current) {
+        ref.current = registerContext(name, params, fetchFn, initialData)
+    }
+    const handle = ref.current
+
+    useEffect(() => {
+        if (handle.getState().status === 'idle') handle.refetch()
+        return () => handle.unregister()
+    }, [handle])
+
+    return useSyncExternalStore(handle.subscribe, handle.getState, handle.getState)
+}
+
+// Internal — wraps an imperative call() with isPending / error state.
+interface MutationHook<TArgs, TResult> {
+    mutate: (args: TArgs) => Promise<TResult>
+    isPending: boolean
+    error: Error | null
+}
+
+function useMutation<TArgs, TResult>(
+    callFn: (args: TArgs) => Promise<TResult>,
+): MutationHook<TArgs, TResult> {
+    const [isPending, setIsPending] = useState(false)
+    const [error, setError] = useState<Error | null>(null)
+
+    const mutate = useCallback(async (args: TArgs) => {
+        setIsPending(true)
+        setError(null)
+        try {
+            return await callFn(args)
+        } catch (e) {
+            setError(e as Error)
+            throw e
+        } finally {
+            setIsPending(false)
+        }
+    }, [callFn])
+
+    return { mutate, isPending, error }
+}
+{% if has_global %}
+// ── Global Context ──
+
+const GlobalCtx = createContext<ContextState<GlobalContextData> | null>(null)
+
+export function GlobalContextProvider({ children }: { children: ReactNode }) {
+    const ssrData = typeof window !== 'undefined' ? (window as any).__MIZAN_SSR_DATA__ : undefined
+    const state = useContextSubscription('global', {}, () => fetchGlobalContext({} as any), ssrData)
+    return <GlobalCtx.Provider value={state}>{children}</GlobalCtx.Provider>
+}
+
+export function useGlobalContext(): ContextState<GlobalContextData> {
+    const ctx = useContext(GlobalCtx)
+    if (!ctx) throw new Error('useGlobalContext requires <MizanContext> or <GlobalContextProvider>')
+    return ctx
+}
+{% for fn in global_fns %}
+export function use{{ fn.pascal }}(): {{ fn.output_type }} | null {
+    return useGlobalContext().data?.{{ fn.name }} ?? null
+}
+{% endfor -%}
+{% endif -%}
+{% for ctx in named_contexts %}
+// ── {{ ctx.pascal }} Context ──
+
+const {{ ctx.pascal }}Ctx = createContext<ContextState<{{ ctx.pascal }}ContextData> | null>(null)
+
+{% if ctx.has_params -%}
+export function {{ ctx.pascal }}Context({ children, ...params }: {{ ctx.pascal }}ContextParams & { children: ReactNode }) {
+    const state = useContextSubscription('{{ ctx.name }}', params, () => fetch{{ ctx.pascal }}Context(params))
+    return <{{ ctx.pascal }}Ctx.Provider value={state}>{children}</{{ ctx.pascal }}Ctx.Provider>
+}
+{% else -%}
+export function {{ ctx.pascal }}Context({ children }: { children: ReactNode }) {
+    const state = useContextSubscription('{{ ctx.name }}', {}, () => fetch{{ ctx.pascal }}Context({} as any))
+    return <{{ ctx.pascal }}Ctx.Provider value={state}>{children}</{{ ctx.pascal }}Ctx.Provider>
+}
+{% endif %}
+export function use{{ ctx.pascal }}Context(): ContextState<{{ ctx.pascal }}ContextData> {
+    const ctx = useContext({{ ctx.pascal }}Ctx)
+    if (!ctx) throw new Error('use{{ ctx.pascal }}Context requires <{{ ctx.pascal }}Context>')
+    return ctx
+}
+{% for fn in ctx.fns %}
+export function use{{ fn.pascal }}(): {{ fn.output_type }} | null {
+    return use{{ ctx.pascal }}Context().data?.{{ fn.name }} ?? null
+}
+{% endfor -%}
+{% endfor -%}
+{% for call in calls %}
+{% if call.has_input -%}
+export function use{{ call.pascal }}() {
+    return useMutation<Parameters<typeof call{{ call.pascal }}>[0], Awaited<ReturnType<typeof call{{ call.pascal }}>>>(call{{ call.pascal }})
+}
+{% else -%}
+export function use{{ call.pascal }}() {
+    return useMutation<void, Awaited<ReturnType<typeof call{{ call.pascal }}>>>(() => call{{ call.pascal }}() as any)
+}
+{% endif -%}
+{% endfor %}
+// ── MizanContext root provider ──
+
+export interface MizanContextProps {
+    /** Base URL for protocol endpoints. Defaults to "/api/mizan". */
+    baseUrl?: string
+    /** Set to `false` for backends without a `/session/` endpoint (e.g. FastAPI). */
+    session?: boolean
+    children: ReactNode
+}
+
+/**
+ * Root provider — calls configure() once and mounts the global context (if defined).
+ * Must wrap any component using Mizan-generated hooks.
+ */
+export function MizanContext({ baseUrl, session, children }: MizanContextProps) {
+    const configured = useRef(false)
+    if (!configured.current) {
+        const opts: Parameters<typeof configure>[0] = {}
+        if (baseUrl !== undefined) opts.baseUrl = baseUrl
+        if (session !== undefined) opts.session = session
+        if (Object.keys(opts).length > 0) configure(opts)
+        configured.current = true
+    }
+{%- if has_global %}
+    return <GlobalContextProvider>{children}</GlobalContextProvider>
+{%- else %}
+    return <>{children}</>
+{%- endif %}
+}
+
+// ── Imperative escape hatch ──
+
+/**
+ * Returns the imperative kernel API. For test harnesses or rare cases where
+ * a typed generated hook does not fit. Most app code should use the typed hooks.
+ */
+export function useMizan() {
+    return { call: mizanCall, fetch: mizanFetch }
+}
+
+export type { ContextState } from '@mizan/base'
+export { configure, initSession, MizanError } from '@mizan/base'
+

protocol/mizan-codegen/templates/rust/Cargo.toml.j2

@@ -0,0 +1,11 @@
+[package]
+name = "{{ crate_name }}"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+mizan-rust = {{ kernel_dep }}
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["rt", "macros"] }
+

protocol/mizan-codegen/templates/rust/call.rs.j2

@@ -0,0 +1,17 @@
+// AUTO-GENERATED by mizan — do not edit
+
+use serde_json::Value;
+
+use mizan_rust::{MizanClient, MizanError};
+
+{% if !type_imports.is_empty() -%}
+use crate::types::{ {{- type_imports|join(", ") -}} };
+
+{% endif -%}
+pub async fn call_{{ snake }}(client: &MizanClient{{ input_param }}) -> Result<{{ return_type }}, MizanError> {
+    let args_value = {{ args_value }};
+    let raw = client.call("{{ name }}", args_value).await?;
+    serde_json::from_value(raw)
+        .map_err(|e| MizanError::transport(format!("decode {{ name }} result: {e}")))
+}
+

protocol/mizan-codegen/templates/rust/context.rs.j2

@@ -0,0 +1,37 @@
+// AUTO-GENERATED by mizan — do not edit
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use mizan_rust::{MizanClient, MizanError};
+
+{% if !type_imports.is_empty() -%}
+use crate::types::{ {{- type_imports|join(", ") -}} };
+
+{% endif -%}
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct {{ pascal }}ContextData {
+{% for field in data_fields -%}
+{% if field.has_rename %}    #[serde(rename = "{{ field.raw_name }}")]
+{% endif %}    pub {{ field.ident }}: {{ field.ty }},
+{% endfor -%}
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct {{ pascal }}ContextParams {
+{% for p in params -%}
+{% if p.has_rename %}    #[serde(rename = "{{ p.raw_name }}")]
+{% endif %}    pub {{ p.ident }}: {{ p.ty }},
+{% endfor -%}
+}
+
+pub async fn fetch_{{ snake }}_context(
+    client: &MizanClient,
+    params: &{{ pascal }}ContextParams,
+) -> Result<{{ pascal }}ContextData, MizanError> {
+    let params_value = serde_json::to_value(params).unwrap_or(Value::Object(Default::default()));
+    let raw = client.fetch_context("{{ ctx_name }}", &params_value).await?;
+    serde_json::from_value(raw)
+        .map_err(|e| MizanError::transport(format!("decode {{ ctx_name }} context: {e}")))
+}
+

protocol/mizan-codegen/templates/rust/lib.rs.j2

@@ -0,0 +1,9 @@
+// AUTO-GENERATED by mizan — do not edit
+
+pub mod types;
+{% if has_contexts %}pub mod contexts;
+{% endif %}{% if has_mutations %}pub mod mutations;
+{% endif %}{% if has_functions %}pub mod functions;
+{% endif %}
+pub use mizan_rust::{MizanClient, MizanConfig, MizanError};
+

protocol/mizan-codegen/templates/rust/mod.rs.j2

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by mizan — do not edit
+
+{% for name in modules -%}
+pub mod {{ name }};
+{% endfor %}

protocol/mizan-codegen/templates/rust/types.rs.j2

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by mizan — do not edit
+
+#![allow(non_camel_case_types)]
+
+use serde::{Deserialize, Serialize};
+
+{{ schemas_block }}
+{{ hoisted_enums_block }}

protocol/mizan-codegen/templates/stage1/call.ts.j2

@@ -0,0 +1,17 @@
+// AUTO-GENERATED by mizan — do not edit
+
+import { mizanCall } from '@mizan/base'
+
+{% if !type_imports.is_empty() -%}
+import type { {{ type_imports|join(", ") }} } from '../types'
+
+{% endif -%}
+{% if has_input -%}
+export function call{{ pascal }}(args: {{ input_type }}): Promise<{{ output_type }}> {
+    return mizanCall('{{ name }}', args)
+}
+{% else -%}
+export function call{{ pascal }}(): Promise<{{ output_type }}> {
+    return mizanCall('{{ name }}', {})
+}
+{% endif %}

protocol/mizan-codegen/templates/stage1/context.ts.j2

@@ -0,0 +1,28 @@
+// AUTO-GENERATED by mizan — do not edit
+
+import { mizanFetch } from '@mizan/base'
+
+{% if !type_imports.is_empty() -%}
+import type { {{ type_imports|join(", ") }} } from '../types'
+
+{% endif -%}
+export interface {{ pascal }}ContextData {
+{%- for field in data_fields %}
+    {{ field.name }}: {{ field.output_type }}
+{%- endfor %}
+}
+
+{% if has_params -%}
+export interface {{ pascal }}ContextParams {
+{%- for p in params %}
+    {{ p.name }}{% if !p.required %}?{% endif %}: {{ p.ts_type }}
+{%- endfor %}
+}
+{%- else -%}
+export type {{ pascal }}ContextParams = Record<string, never>
+{%- endif %}
+
+export function fetch{{ pascal }}Context(params: {{ pascal }}ContextParams): Promise<{{ pascal }}ContextData> {
+    return mizanFetch('{{ ctx_name }}', params)
+}
+

protocol/mizan-codegen/templates/stage1/index.ts.j2

@@ -0,0 +1,20 @@
+// AUTO-GENERATED by mizan — do not edit
+
+export * from './types'
+{% if !contexts.is_empty() %}
+{%- for ctx in contexts %}
+export { fetch{{ ctx.pascal }}Context, type {{ ctx.pascal }}ContextData, type {{ ctx.pascal }}ContextParams } from './contexts/{{ ctx.name }}'
+{%- endfor %}
+{% endif -%}
+{% if !calls.is_empty() %}
+{%- for call in calls %}
+export { call{{ call.pascal }} } from './{{ call.dir }}/{{ call.camel_name }}'
+{%- endfor %}
+{% endif -%}
+{% if !framework_adapters.is_empty() %}
+// Stage 2 framework adapter
+{%- for name in framework_adapters %}
+export * from './{{ name }}'
+{%- endfor %}
+{% endif -%}
+

protocol/mizan-codegen/templates/svelte/svelte.ts.j2

@@ -0,0 +1,31 @@
+// AUTO-GENERATED by mizan — do not edit
+
+import { readable, type Readable } from 'svelte/store'
+import { registerContext, type ContextState } from '@mizan/base'
+
+{% if !stage1_imports.is_empty() -%}
+import { {{ stage1_imports|join(", ") }} } from '../index'
+
+{% endif -%}
+{% for ctx in contexts -%}
+export function create{{ ctx.pascal }}Context({% if ctx.has_params %}params: {{ ctx.pascal }}ContextParams{% endif %}) {
+    const store = readable<ContextState<{{ ctx.pascal }}ContextData>>(
+        { data: null, status: 'idle', error: null },
+        (set) => {
+            const handle = registerContext('{{ ctx.name }}', {{ ctx.params_arg }}, () => fetch{{ ctx.pascal }}Context({{ ctx.params_arg }}))
+            const unsub = handle.subscribe(() => set(handle.getState()))
+            handle.refetch()
+            return () => { unsub(); handle.unregister() }
+        },
+    )
+
+    return store
+}
+
+{% endfor -%}
+{% for call in call_exports -%}
+export { call{{ call }} } from '../index'
+{% endfor %}
+export type { ContextState } from '@mizan/base'
+export { configure, initSession, MizanError } from '@mizan/base'
+

protocol/mizan-codegen/templates/vue/vue.ts.j2

@@ -0,0 +1,65 @@
+// AUTO-GENERATED by mizan — do not edit
+
+import { ref, computed, onMounted, onUnmounted, onServerPrefetch, type ComputedRef } from 'vue'
+import { registerContext, type ContextState } from '@mizan/base'
+
+{% if !stage1_imports.is_empty() -%}
+import { {{ stage1_imports|join(", ") }} } from '../index'
+
+{% endif -%}
+{% for ctx in contexts -%}
+export function use{{ ctx.pascal }}Context({% if ctx.has_params %}params: {{ ctx.pascal }}ContextParams{% endif %}) {
+    const state = ref<ContextState<{{ ctx.pascal }}ContextData>>({ data: null, status: 'idle', error: null })
+    let handle: ReturnType<typeof registerContext> | null = null
+
+    onMounted(() => {
+        handle = registerContext('{{ ctx.name }}', {{ ctx.params_arg }}, () => fetch{{ ctx.pascal }}Context({{ ctx.params_arg }}))
+        handle.subscribe(() => { state.value = handle!.getState() })
+        handle.refetch()
+    })
+
+    onServerPrefetch(async () => {
+        handle = registerContext('{{ ctx.name }}', {{ ctx.params_arg }}, () => fetch{{ ctx.pascal }}Context({{ ctx.params_arg }}))
+        await handle.refetch()
+        state.value = handle.getState()
+    })
+
+    onUnmounted(() => { handle?.unregister() })
+
+    return {
+        state,
+{%- for fn in ctx.fns %}
+        {{ fn.camel_name }}: computed(() => state.value.data?.{{ fn.name }} ?? null) as ComputedRef<{{ fn.output_type }} | null>,
+{%- endfor %}
+        loading: computed(() => state.value.status === 'loading'),
+        error: computed(() => state.value.error),
+    }
+}
+
+{% endfor -%}
+{% for call in calls -%}
+export function use{{ call.pascal }}() {
+    const isPending = ref(false)
+    const error = ref<Error | null>(null)
+{%- if call.has_input %}
+    async function mutate(args: Parameters<typeof call{{ call.pascal }}>[0]) {
+        isPending.value = true; error.value = null
+        try { return await call{{ call.pascal }}(args) }
+        catch (e) { error.value = e as Error; throw e }
+        finally { isPending.value = false }
+    }
+{%- else %}
+    async function mutate() {
+        isPending.value = true; error.value = null
+        try { return await call{{ call.pascal }}() }
+        catch (e) { error.value = e as Error; throw e }
+        finally { isPending.value = false }
+    }
+{%- endif %}
+    return { mutate, isPending, error }
+}
+
+{% endfor -%}
+export type { ContextState } from '@mizan/base'
+export { configure, initSession, MizanError } from '@mizan/base'
+