# Owed Surface

## Contract

This document declares, per crate/package unit, the behavioral mechanisms the unit owes to substantiate the documentation's claims.

- The owed surface is derived from the documentation's CLAIMS. For each non-trivial claim, it enumerates the behaviors the code must exhibit to prove the claim — to a hostile auditor, an IP lawyer, and a paying customer — at maximal performance, efficiency, and hygiene, never a minimal technicality.
- A mechanism is stated as observable behavior with the criterion that distinguishes its maximal realization from a degenerate stub, observably enough that a skeptic can check it.
- A mechanism is owed whether or not the current source realizes it; an unbuilt claim is surfaced, not dropped.
- A **unit** is one crate/package/build target, identified by its root path, sized to emit whole in one `.pack`. A `.pack` targets the units whose roots contain its files.
- This is a declared contract the authoring agent holds and honors when it emits a pack. The PreToolUse gate enforces only that a stance is declared (this document, or an exemption) before code is authored; it does not test the packs.

The AFI's single load-bearing thesis (README.md, docs/AFI_ARCHITECTURE.md § Why the AFI shape): the backends × frontends quadratic collapses to linear because **one KDL IR is the only contract that crosses the backend↔frontend boundary**. Every mechanism below is, in the end, in service of that: N backends emit byte-identical KDL for the same registered functions, and M frontends are generated from it, so a bug can only live in the KDL contract or its edges — nowhere in between.

`backends/mizan-django/src/mizan` exceeds the single-emit budget (137K est. tokens); it is decomposed below into sub-units along the documented feature seams (dispatch, cache, channels, forms, shapes, ssr, jwt, registration/export) plus its verification harness, which itself exceeds budget and is cut into two test sub-units at the protocol-vs-adversarial seam. Every other unit emits whole.

---

## Unit: mizan_core (`cores/mizan-python/src/mizan_core`)

**Charter.** The framework-agnostic Python substrate every Python backend adapter stands on: the `@client` decorator and the function-to-IR machinery, the registry, canonical KDL IR emission, HMAC cache-key derivation, cache backends, MWT identity, and the type-introspection helpers the adapters share. It owns *language-level* primitives; it does not own transport, dispatch, or any Django/FastAPI mechanics.

**Claims substantiated here.**
- Client Function RPC — decorated functions carrying the full variadic/kwarg set (INVARIANTS.md § Client Function RPC).
- Named Contexts — functions sharing a context name grouped at registration into one provider/one fetch (INVARIANTS.md § Named Contexts; MIZAN.md §1–2).
- Mutation Invalidation & merge — `affects=`/`merge=` carried in the IR, never middleware (INVARIANTS.md § Mutation Invalidation; MIZAN.md §4).
- Auth as a property of the declared function, carried in the IR (INVARIANTS.md § Auth; MWT_SPEC.md § Usage rule).
- Canonical KDL IR — every backend emits KDL describing functions/contexts/types/invalidation graph; the IR is the only contract (INVARIANTS.md § Canonical IR & Codegen; docs/AFI_ARCHITECTURE.md § KDL is the IR).
- HMAC cache keying with cross-language conformance (docs/CACHE_KEYING.md; ROADMAP.md § HMAC cache keying).
- MWT identity layer (docs/MWT_SPEC.md).
- Free origin-side cache implementing the full protocol locally (docs/PRODUCT_ARCHITECTURE.md § Free framework).
- File Uploads — `Upload` first-class end to end through IR (INVARIANTS.md § File Uploads).

**Owed behavioral mechanisms.**

Client Function RPC / decorator:
- `@client` accepts the full declared set (`context`, `affects`, `merge`, `private`, `route`, `methods`, `websocket`, `auth`, `rev`, `cache`) and synthesizes a Pydantic `Input` model from the function signature (skipping the request param) — observable: a decorated fn with `(request, a: int, b: int)` yields an `Input` with two typed fields; input validation rejects `a="x"` before the body runs.
- the return annotation decides wire shape: a primitive/dict return is wrapped as `{result: …}`, while `BaseModel` / `list[BaseModel]` / `Optional[BaseModel]` pass through bare — observable: `-> list[Item]` reaches the wire as a bare JSON array, `-> int` as `{"result": n}`; a missing return annotation raises `TypeError` at decoration (not a silent `Any`).
- `context=` and `affects=` (and `merge=`) are enforced mutually exclusive at decoration — observable: `@client(context=X, affects=Y)` raises `ValueError`, so a function cannot be simultaneously a reader and a mutation.
- `auth=` is normalized and validated at decoration (`True`→`"required"`, callables kept, `"staff"/"superuser"` allowed) — observable: `@client(auth="admin")` raises `ValueError` naming the valid set, not a runtime surprise at dispatch.

Named Contexts grouping (the "one provider, one fetch" invariant's registry half):
- the registry groups every function by its context string so a named context is a single fetch unit, never N callables — observable: two `@client(context="user")` functions produce `get_context_groups()["user"] == [both names]`; `"global"` is just a reserved name in the same map, not a separate mechanism.
- OWED (unbuilt): mixing socket and non-socket transport within one context is a registration-time error (INVARIANTS.md § WebSocket Support) — observable when built: registering a `websocket=True` fn and a plain fn under the same `context=` raises at registration; no such check exists in the registry today, so this obligation is currently unsubstantiated.
- OWED (unbuilt): `receive` defined without `send`, and `affects` referencing a non-existent context/function, are registration-time errors (MIZAN.md §6) — `validate_registry()` warns on unresolved `affects` targets but does not hard-error, and there is no `send`/`receive` class to validate.

Canonical KDL IR (`build_ir`) — the contract every codegen target reads:
- IR is emitted in a canonical order independent of registration order (functions alphabetical by wire name, contexts alphabetical, params alphabetical, `shared-by` sorted) — observable: registering the same functions in two different orders yields byte-identical KDL; this is the property the three-way parity test rests on.
- types are introspected from the Pydantic models directly (never routed through JSON-Schema `$ref`), producing `struct` / `alias{list}` / `enum` / `optional` / `union` shapes under canonical `<camelName>Input` / `<camelName>Output` names, with `Vec`-element sub-types surfaced — observable: a `-> list[OrderOutput]` fn emits `type "userOrdersOutput" { alias { list { ref "OrderOutput" } } }` AND a `type "OrderOutput" { struct … }`; `-> Model | None` sets `output-nullable #true`.
- context param elevation is computed in the IR: a param is `required #true` iff every member of the context declares it, with `shared-by` naming the declarers — observable: a two-function `user` context where both take `user_id` emits `param "user_id" { type "integer"; required #true; shared-by … }`; if only one declares `page`, `page` is `required #false`.
- `private` and view-path functions are omitted from the emitted `function` set, and channels are emitted from the `channels` registry extension — observable: `@client(private=True)` never appears in the KDL (so it can carry invalidation without being client-callable); a registered channel emits a `channel` node with its pascal-name and message-type refs.

HMAC cache keying (protocol-critical cross-language identity):
- `derive_cache_key` produces `ctx:{context}:{hmac_hex}` over a JSON-canonical sorted form with param values normalized to JSON-native strings (`True`→`"true"`, `None`→`"null"`) and `user_id` omitted for public content — observable: the pinned test vectors (`ctx:user:605a1ca5…` public, `ctx:user:30fc08eb…` user-scoped) match the TypeScript adapter byte-for-byte; param ordering does not change the key; the `ctx:` prefix supports broad SCAN.
- key derivation resists delimiter collision and versions on `rev` — observable: `context="user", user_id="12"` and `context="user1", user_id="2"` produce different keys; bumping `rev` produces a new key, so old entries become unreachable orphans without a purge.

MWT identity layer:
- `create_mwt` places `kid` in the JOSE header per RFC 7515 (not the payload) and computes `pkey` as `sha256` over `sorted(get_all_permissions())` plus staff/super flags, with `aud` and `nbf` claims — observable: `decode_mwt` reads `kid` from the header; a token minted for one audience decodes to `None` under another; `pkey` is deterministic for identical permission state and changes the instant a permission is added.
- `MWTUser` is built entirely from claims with no DB query — observable: constructing `MWTUser(payload)` sets `pk`/`is_staff`/`is_superuser`/`pkey` from the token alone; an expired token decodes to `None`.

Cache backends:
- `MemoryCache` and `RedisCache` both implement get/set/delete plus prefix-scoped purge; the Redis broad purge SCANs `ctx:{context}:*` and UNLINKs, never a full flush — observable: `delete_by_prefix("ctx:user:")` removes only `user` entries and leaves `ctx:products:*` and foreign-prefixed keys intact; `RedisCache` applies a TTL safety-net on every `set`.

Type-introspection helpers (shared so backend parity cannot drift):
- `is_structured_output` recognizes `BaseModel` / `Optional[BaseModel]` / container-of-`BaseModel` as no-wrap, and `types_match_for_merge` accepts direct / list-upsert / list-replace shape matches — observable: a slot typed `list[T]` matches a value typed `T` (upsert-by-id), and a multi-arm `A | B | None` union is returned as-is by `extract_optional`, not silently narrowed to one arm.

File Uploads — OWED (unbuilt):
- an `Upload` type is a first-class argument carried through IR, codegen, and dispatch binding, bound from multipart over HTTP and from the envelope over IPC (INVARIANTS.md § File Uploads) — observable when built: a function declaring an `Upload` parameter emits a distinguished IR shape and binds a real file object at dispatch; no `Upload` type exists anywhere in the source today, so this claim is entirely unsubstantiated.

---

## Unit: mizan-rust core (`cores/mizan-rust`)

**Charter.** The Rust analog of `mizan_core`: the IR data model, a KDL emitter that is byte-equivalent to the Python emitter, the compile-time (linkme) registry, the runtime invalidation/merge resolvers the HTTP and Tauri adapters call, and the cross-function graph checks. It owns the Rust side of the *same* IR contract; it does not own transport.

**Claims substantiated here.**
- Canonical KDL IR — "the IR must be validated against multiple adapters"; Rust is an IR authority (docs/AFI_ARCHITECTURE.md § KDL is the IR; README.md note 6).
- Mutation invalidation auto-scoping (three-tier) and merge on the Rust adapters (README.md § Adapters; § Merge via `mizan-tauri`/`mizan-rust-axum`).
- The IR is the only contract — divergence between adapters is what it exists to prevent (docs/AFI_ARCHITECTURE.md § KDL is the IR).

**Owed behavioral mechanisms.**

Byte-equivalent KDL emission:
- `build_ir()` produces KDL byte-identical to the Python emitter against the same registered functions/types/contexts — observable: `cores/mizan-rust/tests/afi_parity.rs` and the three-way `tests/afi/test_codegen_parity.py` diff Rust output against the canonical Python-emitted `afi_ir.kdl` and require exact equality (line-by-line failure on any drift).
- the emitter reproduces the Python emitter's canonicalization exactly: alphabetical functions/contexts, sorted params, `shared-by`, snake→camel conversion, primitive-alias/enum inlining, and tree-shaking to types reachable from a registered function's input/output — observable: a `#[derive(Mizan)]` type not referenced by any function is omitted; an `Alias(Primitive)` or `Enum` named type inlines at its reference site instead of emitting a standalone `type` node, matching the Python output.

Compile-time registry:
- `TYPES` / `CONTEXTS` / `FUNCTIONS` are linkme distributed slices populated at the consumer crate's expansion sites, and `lookup_function` / `context_members` resolve against them — observable: an IR-export bin that references one symbol per module force-links its registrations; dropping the reference drops the function from the emitted IR (the documented force-link requirement is real, not decorative).

Runtime invalidation & merge (must match the Python executor's semantics):
- `compute_invalidation` auto-scopes by matching mutation arg names against the affected context's declared Input params — observable: a mutation carrying `user_id` against a `user` context whose members declare `user_id` emits `{context:"user", params:{user_id:…}}`, while a non-matching arg emits the bare context string.
- `compute_merges` resolves the slot by structural return-type match against context members (via `types_match`), emitting `{context, slot, value}` only on a unique match and dropping ambiguous/no-match — observable: with two context members of different output shapes, a mutation's value routes to the single member whose type matches; two matching members drop the merge (fall back to refetch), never a bundle-order guess.

Cross-function graph checks (fail at IR-build time, before any client is emitted):
- `verify_invariants` panics with a structured message when an `affects`/`merge` target names an unregistered context, when a `merge` target has no unique matching member, or when a shared context param's type diverges across members — observable: an `affects = "ghost"` fails codegen with a named error; a `merge` whose context has two same-type members fails naming both; this is the whole-graph consistency the "IR prevents divergence" claim rests on.

---

## Unit: mizan-rust-macros (`cores/mizan-rust-macros`)

**Charter.** The proc macros — `#[derive(Mizan)]`, `#[mizan::context]`, `#[mizan::client]` — that make the Rust consumer surface author the same registry and IR shapes the Python decorator produces. It owns the compile-time codegen that emits `MizanType`/`FunctionSpec` impls and linkme registrations; it does not own runtime behavior.

**Claims substantiated here.**
- Rust/Tauri are "the IR authority via the `#[mizan::client]` macro + linkme registry" (README.md note 6).
- The `#[mizan::client]` surface mirrors the Python `@client` parameter set (backends/mizan-tauri/README.md § Define server functions; backends/mizan-rust-axum README).

**Owed behavioral mechanisms.**
- `#[derive(Mizan)]` emits a `MizanType::shape()` matching the Python type introspection, honoring serde `rename_all`/`rename` so wire names match serialization, and registers a `TypeEntry` — observable: an enum with `#[serde(rename_all="snake_case")]` emits IR enum variants in snake form; a struct field `r#type` emits IR field name `type`.
- `#[mizan::client]` synthesizes a `<camelName>Input` struct + `MizanType` impl, registers the canonical `<camelName>Input`/`<camelName>Output` type entries (and the `Vec` element type for list outputs), and implements `FunctionSpec::dispatch` that deserializes JSON args into the typed input, awaits the body, and serializes the result — observable: `async fn user_orders(req, user_id: i64) -> Vec<OrderOutput>` registers `userOrdersOutput` as a list alias plus `OrderOutput`, and dispatch round-trips typed args; a `Result<T, MizanError>` return `?`-unwraps so user errors surface as the standard envelope, while the IR still sees only the `T` shape.
- `#[mizan::client]` enforces the same mutual-exclusion as Python (`context` vs `affects`/`merge`) and requires an `async fn` with an explicit return type — observable: `#[mizan::client(context = X, affects = Y)]` is a compile error; a non-async or return-typeless fn is a compile error.
- `#[mizan::context]` emits a `ContextMarker` with a snake_case (or explicit) name and registers a `ContextEntry` — observable: `#[mizan::context("user")]` and `#[mizan::context] struct UserCtx` both yield `NAME == "user"`; a non-unit struct is a compile error.
- input-param wire names strip the Rust `_`-underscore convention and bridge it with `#[serde(rename)]` — observable: `_user_id: i64` emits IR param name `user_id` and the synthesized Input renames the JSON key so dispatch deserializes the wire form.

---

## Unit: mizan-rust-ssr (`cores/mizan-rust-ssr`)

**Charter.** The embedded-V8 SSR engine, its PyO3 binding, and the anti-RSC guard. It owns rendering a build-time JS bundle to HTML in-process via `deno_core`, exposing that engine to the Python side across an in-process FFI boundary, and the structural guarantee that the SSR surface never imports an RSC/Flight runtime. It does not own the Django template backend (that is `mizan-django/ssr`) or the bundling that produces the JS bundle (that is `mizan-generate`).

**Claims substantiated here.**
- SSR is hand-rolled; no frontend adapter imports an SSR runtime or meta-framework (Next/Nuxt/SvelteKit/RSC/Flight) — the CVE-2025-55182 pre-auth-RCE deserialization class (HOLOMORPHICS/Mizan project note; MEMORY: mizan-ssr-no-framework-runtimes; enforced by `cores/mizan-rust-ssr/tests/no_rsc.rs`).
- SSR renders synchronously from props, injected as validated data (the AFI provides the typed one-way version).
- The Python side binds the engine through PyO3 — in-process FFI, no subprocess, no JSON-RPC framing; behavior lives in the binary, languages bind to it (docs/SSR_ARCHITECTURE.md § The engine; § AFI boundary; ROADMAP.md § Core Consolidation — SSR in the binary).

**Owed behavioral mechanisms.**
- the engine composes a real `deno_web` web-platform layer (TextEncoder/Decoder, MessagePort, timers) rather than a partial shim, evals the trusted bundle once, and renders per request — observable: the fixture bundle renders `Hello, World!`; a missing global would fail loudly at render, not silently pass (the doc's "partial polyfill is silent-failure-shaped" concern is discharged by using deno_web's real impls).
- props cross as a `v8::json::parse`d value passed as a function argument, never spliced into evaluated source — observable: the injection test feeds a prop string crafted to break out of a string-built call; it renders as inert text and does not set a global, so code injection is structurally absent.
- the no-RSC guard scans authored SSR source and dependencies for the forbidden token set (`react-server-dom`, `renderToReadableStream`, `renderToPipeableStream`, `createFromReadableStream`/`Fetch`, `use server`, `next/`, `nuxt`, `@sveltejs/kit`) and fails on presence — observable: adding any RSC/Flight/meta-framework import to the scanned fixtures turns `no_rsc.rs` red; absence alone is not the guarantee — re-entry is loud.
- OWED (unbuilt): a PyO3 binding exposes `SsrEngine` to the Python side as an in-process extension — construct-from-bundle and `render(props_json) -> HTML` cross the FFI boundary with no process spawn, honoring V8's one-isolate-per-engine / non-`Send` constraint so the caller holds one engine per (worker thread, bundle) — observable when built: the Django backend imports the engine and calls `render(props)` in-process, and a prop still crosses as a parsed value (the injection guarantee survives the FFI hop). Today `cores/mizan-rust-ssr/src/lib.rs` exposes `SsrEngine` only as a Rust API with Rust-native `#[tokio::test]` coverage and carries no `#[pyclass]`/`#[pymodule]`, so the PyO3 surface the AFI-boundary table names is unsubstantiated.

---

## Unit: mizan-django dispatch (`backends/mizan-django/src/mizan/client`)

**Charter.** The Django HTTP/RPC dispatch surface: the executor that validates input, enforces auth, runs the function, and branches RPC-vs-view; the invalidation and merge resolvers; the context-bundle fetch; JWT/MWT request authentication. It owns per-request Django dispatch semantics; it does not own the registry, the IR, or the cache implementation (it calls them).

**Claims substantiated here.**
- RPC call dispatch returning `{result, invalidate}` and `merge` (README.md; MIZAN.md §4).
- Named-context bundle fetch — one GET returns all functions in the context, never N round-trips (INVARIANTS.md § Named Contexts; MIZAN.md §3).
- Mutation invalidation with three-tier auto-scoping; on failure nothing invalidates; developer writes no cache key (INVARIANTS.md § Mutation Invalidation).
- Auth enforced at dispatch, rejecting before the body runs, identically across transports (INVARIANTS.md § Auth; MWT_SPEC.md § Usage rule).
- Both invalidation transports: JSON body and `X-Mizan-Invalidate` header (ROADMAP.md § Done).
- Return-type branching: data → RPC path, `HttpResponse` → view path (ROADMAP.md § Done).
- Origin-side HMAC cache read/write on context fetch; `cache=False`/`rev` policy (docs/CACHE_KEYING.md; docs/PRODUCT_ARCHITECTURE.md § Spec additions).
- MWT/JWT server-side auth enforcement in the executor (`_check_auth_requirement`) (docs/MWT_SPEC.md § Usage rule).

**Owed behavioral mechanisms.**

Dispatch & validation:
- `execute_function` validates input against the function's Pydantic `Input` before invoking the body, and rejects private functions from RPC — observable: a missing required field returns `VALIDATION_ERROR` with per-field detail and the body never runs; a `private=True` function returns `FORBIDDEN` when called over `/call/`.
- output serialization walks `BaseModel`/`list`/`dict` recursively via `to_jsonable_python` so `list[BaseModel]` reaches the wire as a bare array — observable: a `-> list[Item]` function returns `[{…},{…}]`, not `{"result":[…]}`; an `Optional[Model]` returning `None` serializes to `null` not `{"result":null}`.

Named-context bundle fetch (single request, param-filtered):
- `execute_context` runs every function in the group in one request, passing each only the params it declares, and fails the whole bundle if any member fails auth/validation — observable: `GET /ctx/user/?user_id=5&page=3` returns `{user_profile:…, user_orders:…}` where `user_profile` never sees `page`; if one member requires auth and the request is anonymous, the whole fetch returns the auth error, not a partial bundle.

Three-tier invalidation (the invariant that separates the AFI from typed RPC):
- `_resolve_invalidation` auto-scopes by matching mutation args against context param names (Tier 1), falling back to the bare context (Tier 3), and resolves function-level `affects` to the function name — observable: `update_profile(user_id=5,…)` against a `user` context emits `[{context:"user", params:{user_id:5}}]`; a mutation whose args don't overlap emits `["user"]`; `affects="user_profile"` emits the function name as the key.
- invalidation is emitted on both transports and only on success — observable: a successful mutation carries both `response["invalidate"]` (JSON body) and `X-Mizan-Invalidate: user;user_id=5` (header, URL-encoded so `q=hello world`→`q=hello%20world` and semicolons survive a parse round-trip); a mutation that raises emits neither.
- `_resolve_merges` resolves the merge slot server-side by matching the mutation's Output type against context members' Output types (`types_match_for_merge`), emitting `{context, slot, value, params?}` only on a unique match — observable: with `morph_groups: list[MorphGroupMeta]` and `morph_layers: list[MorphLayer]` in one context, a mutation returning `MorphLayer` merges into `morph_layers` only; the kernel does no shape inference.

Auth enforced before the body:
- `_check_auth_requirement` runs before `view.call`, handling `required`/`staff`/`superuser`/callable and mapping to `UNAUTHORIZED`/`FORBIDDEN` — observable: an anonymous call to `@client(auth=True)` returns `UNAUTHORIZED` and the function body never executes; a callable raising `PermissionError` surfaces its message as `FORBIDDEN`.
- MWT is checked first (`X-Mizan-Token`), then legacy JWT (`Authorization: Bearer`), then session+CSRF; a present-but-invalid token is rejected (never a silent fall-through to session) — observable: an invalid `X-Mizan-Token` returns 401 without trying session auth; a valid MWT sets `request.user = MWTUser` with no DB query; CSRF is enforced only on the session path.

Return-type branching + origin cache:
- a function returning an `HttpResponse` takes the view path (invalidation rides the header, `Cache-Control: no-store`), while a data return takes the RPC path — observable: a `-> HttpResponseRedirect` mutation returns the 302 with `X-Mizan-Invalidate` set; the same-decorated `-> Shape` mutation returns JSON with `invalidate` in the body.
- context fetch consults the origin cache keyed by the effective `rev` (max across members) and effective cache policy (`False` short-circuits), stores deterministic (sorted-key) JSON on miss, and purges scoped/broad on mutation — observable: two identical fetches return byte-identical bodies and the second carries `X-Mizan-Cache: HIT`; a scoped mutation for `user_id=5` purges only that entry and leaves `user_id=6` a HIT; a context with any `cache=False` member emits `no-store`.

---

## Unit: mizan-django cache (`backends/mizan-django/src/mizan/cache`)

**Charter.** The Django-side origin cache facade over `mizan_core`'s backends and key derivation — the free, unit-testable local cache that implements the same HMAC key and purge semantics as the paid Edge. It owns cache lifecycle/config resolution and the scoped-vs-broad purge dispatch; it does not own key derivation (delegates to core).

**Claims substantiated here.**
- Free framework origin-side cache implementing the full cache protocol locally, same HMAC key and purge as Edge (docs/PRODUCT_ARCHITECTURE.md § Free framework; docs/CACHE_KEYING.md § Cache architecture).
- Scoped purge recomputes the key and deletes directly; broad purge SCANs the `ctx:{context}:*` prefix (docs/CACHE_KEYING.md § Required operations; backends/mizan-django/src/mizan/cache/KNOWN_ISSUES.md).

**Owed behavioral mechanisms.**
- `cache_purge` recomputes the exact HMAC key for a scoped purge (one DELETE) and prefix-scans for a broad purge, so scoped invalidation touches exactly one entry — observable: `cache_purge(ctx, {user_id:5}, secret)` deletes only user 5's entry (returns 1) and leaves user 6; `cache_purge(ctx)` with no params removes every entry under the prefix.
- cache enablement is gated on both `cache_secret` and `cache_redis_url` present, thread-safe and lazily initialized — observable: with only one configured, caching is disabled and logged; concurrent `get_cache()` calls initialize once.
- OWED (open, per KNOWN_ISSUES.md): purge atomicity (index read/delete race), cross-language stringification for all value types (not just bool/None), per-param sub-index cleanup on broad purge, thundering-herd/single-flight protection, `cache_get`/`cache_put` argument-shape consistency, and RedisCache test coverage — each is a named correctness/operability obligation the "same protocol as Edge, security-critical" claim rests on and that the source has flagged as not-yet-satisfied.

---

## Unit: mizan-django channels (`backends/mizan-django/src/mizan/channels`)

**Charter.** The WebSocket transport: the `ReactChannel` base + registry, the multiplexed consumer that handles channel subscribe/message and RPC-over-WS, server push, and channel schema export. It owns real-time bidirectional messaging and WS-transported RPC; it does not own HTTP dispatch (reuses the executor).

**Claims substantiated here.**
- WebSocket support: `websocket=` dispatched over a persistent connection; server-initiated messages reach subscribed contexts; declaration and wire semantics uniform across adapters (INVARIANTS.md § WebSocket Support).
- WebSocket channels — typed bidirectional communication, real-time (ROADMAP.md § Done).
- Channels compose into the IR channel section (docs/AFI_ARCHITECTURE.md — codegen channels target consumes the channel nodes).
- Auth/authorization checked before any channel or RPC body runs (INVARIANTS.md § Auth; consumer security).

**Owed behavioral mechanisms.**
- the consumer multiplexes many channel subscriptions and RPC calls over one socket, keyed by `(channel, params_json)`, and validates Pydantic params/messages before `authorize`/`receive` — observable: subscribing with a wrong-typed param returns an error before authorization; a duplicate subscription to the same `(channel, params)` is rejected; unsubscribe leaves zero lingering subscriptions after rapid subscribe/unsubscribe cycles.
- WS-RPC only dispatches functions explicitly marked `websocket=True`, running the same `execute_function` (so validation/auth are identical to HTTP) — observable: an RPC call to an HTTP-only function returns `FORBIDDEN` ("use POST /call/"); a WS call to a `websocket=True` fn returns the same envelope shape as HTTP; a missing `id`/`fn` returns a structured error.
- `authorize()` gates every subscription and exceptions in it are contained — observable: `authorize` returning `False` blocks the subscribe with "Not authorized"; an `authorize` that raises returns an error rather than crashing the socket; room-level authorization enforces per-param access (room 1 allowed, room 999 rejected).
- server push (`push`/`ReactChannel.push`) broadcasts to the channel-layer group, converting Pydantic to JSON, so a server function can reach subscribers — observable: `ChatChannel.push(room="general", message=…)` sends to `chat_general` with the message body; push with no channel layer configured warns rather than raising.
- channel schema is exported into the registry's `channels` extension carrying params/react/django message shapes and a `bidirectional` flag — observable: a channel with a `ReactMessage` reports `bidirectional: true`; a push-only channel reports `false` and omits `react_message`, and the codegen channels target emits the matching typed envelopes and `useXChannel` hook.
- JWT auth over the WS handshake authenticates from the `?token=` query param without a DB query, taking precedence over session — observable: a valid access token sets `scope["user"]` to a `JWTUser` from claims; an invalid token falls back to session rather than rejecting the socket.

---

## Unit: mizan-django forms (`backends/mizan-django/src/mizan/forms`)

**Charter.** The Forms composition: `mizanFormMixin`/`mizanFormMeta` turning a Django Form into the three role-tagged server functions (schema/validate/submit), plus formsets, and the field schema/validation projection. It owns Django-Form-to-server-function translation; it does not own generic RPC dispatch. Auth-provider (django-allauth) forms are **out of scope** — the docs place them in a dedicated external `mizan-allauth` repository built on this mixin; this unit owes only the primitive they build on.

**Claims substantiated here.**
- Forms are three role-tagged client functions (schema / validate / submit) plus field validation, composed from RPC + validation (INVARIANTS.md § Compositions — Forms).
- Forms (schema/validate/submit) and formsets as Django stack extensions (ROADMAP.md § Done).
- Auto-registers `{name}.schema` / `.validate` / `.submit`; frontend gets `useXForm()` (backends/mizan-django/README.md § Forms).

**Owed behavioral mechanisms.**
- `mizanFormMixin.__init_subclass__` auto-registers exactly three role-tagged server functions per concrete form (and formset variants when enabled), carrying `form`/`form_name`/`form_role` meta — observable: defining a `ContactForm` with a `mizanFormMeta(name="contact")` registers `contact.schema`, `contact.validate`, `contact.submit`; a form without a `mizan` attribute registers nothing; enabling `enable_formset` adds `contact.formset.{schema,validate,submit}`.
- the schema function projects each Django field into a typed `FieldSchema` (mapping field classes to Python types, extracting choices from `ModelChoiceField` safely, serializing initial values) and carries the `mizanFormMeta` display/behavior settings — observable: a `CharField`/`EmailField`/`Textarea` form yields three typed fields with correct `type`/`widget`; a `ModelChoiceField` yields JSON-serializable `{value,label}` choices (no `ModelChoiceIteratorValue` leak).
- validate runs the real Django form validation and returns structured per-field errors; submit branches multipart-vs-JSON, calls the form's `on_submit_success`/`on_submit_failure`, and returns pass/fail with data — observable: submitting an invalid email returns field errors and `success: false`; a valid submit runs `on_submit_success` and returns its data; a multipart submit binds files.
- `create_form_instance` threads `request`/`user`/`instance` init kwargs into the Django form and gracefully drops any the form doesn't accept, so the mixin is a reusable primitive for forms that need request context (the base the external `mizan-allauth` repo builds on) — observable: a form declaring a `request` kwarg receives it; a form that doesn't accept `request` still instantiates rather than raising `TypeError`.
- OWED (open, ISSUES.md § Open / ROADMAP.md § Next): a forms codegen target wired to `mizanCall` from the kernel, retiring the hand-written `mizan-react/src/forms.ts` — observable when built: the codegen emits form clients against the kernel; today no form codegen target exists, so the frontend form surface still depends on the pre-kernel provider.

---

## Unit: mizan-django shapes (`backends/mizan-django/src/mizan/shapes`)

**Charter.** The "API Shapes" primitive: Pydantic-typed queryset projection over django-readers, PK-keyed structural diffing (add/modify/delete) across nested relations. It owns ORM projection and diff derivation; it does not own dispatch.

**Claims substantiated here.**
- API Shapes to the fullest extent: ORM integration, auto-diffing by primary key (add/modify/delete, Django as reference), authorable near the used function (INVARIANTS.md § API Shapes).
- Shapes — Pydantic + django-readers for typed query projections (ROADMAP.md § Done).
- Context classes send/receive with Shape diffing (INVARIANTS.md § Compositions — Context classes; MIZAN.md §5).

**Owed behavioral mechanisms.**
- `Shape.query` compiles a django-readers projection from the Pydantic field set + nested Shapes, executing minimal queries (single query for flat, prefetch for nested) and validating each row — observable: a flat shape query runs one SQL query; a nested `AuthorCardShape` with `books` runs two (prefetch), not N+1; per-relation querysets filter nested rows (`books=lambda qs: qs.filter(is_published=True)`).
- diffing computes add/modify/delete by primary key across nested relations, using a single batched query for existing rows and strict access to nested diffs — observable: `diff_many` of mixed new+existing items runs one query for the existing set; a nested diff reports `created`/`updated`/`deleted` by child PK; accessing a mistyped nested name raises (KeyError/AttributeError) rather than silently returning empty.
- PK/type resolution handles integer, slug, and UUID primary keys, two FKs to the same model, self-referential and nullable FKs, and treats `False`/`0`/`""` as present values — observable: a UUID-PK `Section` shape diffs correctly; `is_published=False` is not treated as missing; a nullable editor FK returns `None` rather than erroring.
- OWED (unbuilt): the `ReactContext('name')` class form with `send`/`receive` and a `POST /ctx/<name>/commit/` endpoint that routes committed shape data to `receive`, with auto-refetch-or-fresh-return after commit (INVARIANTS.md § Compositions; MIZAN.md §5) — observable when built: a class defining `send`/`receive` generates a read hook and a commit function; committing runs `receive` and either refetches or uses a returned Shape. Today `ReactContext` is only a context-name marker with no metaclass, `send`/`receive`, or commit endpoint — the class form is unsubstantiated.

---

## Unit: mizan-django SSR (`backends/mizan-django/src/mizan/ssr`)

**Charter.** The SSR product's Django half: a Django template backend that renders `.tsx`/`.jsx` component files by resolving each to its built bundle and driving the PyO3-bound `SsrEngine` in-process, wrapping output with a hydration payload. It owns the Django-template-engine integration, component-to-bundle resolution, prop gathering, and the per-(worker-thread, bundle) engine lifecycle; it does not own the V8 render (that is `cores/mizan-rust-ssr`'s `SsrEngine`) or the bundling that produces the render bundle (that is `mizan-generate`).

**Claims substantiated here.**
- SSR is a Django template backend replacing the rendering engine; the template name IS a `.tsx`/`.jsx` file path; context dict becomes props; output wrapped in `<div id="mizan-root">` + `window.__MIZAN_SSR_DATA__` hydration (docs/SSR_ARCHITECTURE.md).
- The render engine is embedded-V8 inside the Mizan Rust binary, bound via PyO3 — in-process FFI, no external JS runtime serving requests, no subprocess, no JSON-RPC framing (docs/SSR_ARCHITECTURE.md § The engine; § AFI boundary — Backend adapter row).
- The component path resolves against `DIRS` to its built bundle in `OPTIONS['bundles']` (produced by mizan-generate's SSR bundling step); the backend gathers props and wraps output for hydration (docs/SSR_ARCHITECTURE.md § AFI boundary — Backend adapter row; the `TEMPLATES` config block).
- One engine per (worker thread, bundle) — V8's Locker constraint makes an engine non-`Send`, so the Django side never shares one across threads (docs/SSR_ARCHITECTURE.md § The engine).
- SSR is orthogonal to RPC and composable; first paint carries data (INVARIANTS.md § SSR).

**Owed behavioral mechanisms.**
- `MizanTemplates` implements Django's template-backend interface: `get_template(name)` resolves `name` as a `.tsx`/`.jsx` file path under `DIRS` and returns a `MizanTemplate` for the resolved component; `render` strips `request`/`csrf_token` and passes the remaining context as props — observable: `render(request, 'components/Hello.tsx', ctx)` renders that component with `ctx` as props; `from_string` raises (it renders files, not strings); a missing file raises `TemplateDoesNotExist`.
- component-to-bundle resolution: the backend resolves each component file to its self-contained render bundle in `OPTIONS['bundles']` (the `mizan-generate`-produced bundle assigning `globalThis.renderApp`) and hands the bundle to the engine, rather than reading component source directly — observable: `render` of `components/Hello.tsx` loads that component's built bundle from the configured `bundles` directory; a component with no built bundle raises rather than rendering stale or empty HTML.
- rendered output is wrapped for client hydration — observable: output contains `<div id="mizan-root">…</div>` plus `<script>window.__MIZAN_SSR_DATA__={sorted-json}</script>`, so first paint carries the props the client hydrates from.
- engine lifecycle: the backend constructs one `SsrEngine` per (worker thread, bundle) pair and reuses it across requests, never sharing a single engine across threads (the engine is non-`Send`) — observable: concurrent renders on different worker threads each use their own thread-local engine and return correct results with no interleaving; the engine is built once per bundle, not per render.
- OWED (unbuilt — the PyO3 cutover): the Django backend binds the engine through PyO3 and renders in-process — no `bun run` subprocess, no newline-delimited JSON-RPC, no `SSRBridge`, no ready-signal / auto-restart machinery, and `OPTIONS` carries `bundles` (a directory of built bundles) rather than `worker` (a JS entry file) — observable when built: a render spawns no external JS runtime process and calls the PyO3-bound `SsrEngine.render(props)` directly; `ssr/bridge.py` and the `workers/mizan-ssr` worker are retired. Today this is entirely unsubstantiated: `ssr/bridge.py` spawns `bun run <worker>` and correlates requests over JSON-RPC, `ssr/backend.py` wires `OPTIONS['worker']` to that bridge and renders via `SSRBridge.render`, and the docstrings still describe a "persistent Bun subprocess" — the subprocess architecture the docs (§ The engine, § AFI boundary) no longer describe.
- OWED (partial, docs/PSR_VS_EDGE.md § Current state): the render-on-mutation orchestration (mutation → trigger local render → store HTML), driven by the manifest's `render_strategy`, wiring the engine to the PSR path — observable when built: a public-context mutation triggers a local re-render and stores HTML; today the engine renders on request and the manifest records the strategy, but the mutation→render→store wiring is absent, so PSR-on-mutation is unsubstantiated.

---

## Unit: mizan-django JWT/MWT (`backends/mizan-django/src/mizan/jwt`)

**Charter.** The Django identity layer: JWT access/refresh tokens tied to sessions, the MWT-mint server functions, JWT settings/algorithm resolution, and the Ninja security class. It owns Django-session-bound token issuance and validation; the MWT format itself lives in `mizan_core.mwt`.

**Claims substantiated here.**
- JWT auth (access/refresh, session validation) auto-detected, CSRF handled (ROADMAP.md § Done).
- MWT is issued from an authenticated identity; `create_mwt(user, secret, ttl, audience, kid)`; a separate JWT module still exists for user-auth tokens (docs/MWT_SPEC.md § Key decisions).
- MWT is the cache-keying identity, not a replacement for JWT auth (docs/MWT_SPEC.md).

**Owed behavioral mechanisms.**
- JWT tokens carry `sub`/`sid`/`staff`/`super`/`type`/`iat`/`exp` and are tied to a session key so logout revokes them — observable: a refresh whose underlying session was destroyed returns `None` (immediate revocation); an access `JWTUser` is built from claims with no DB query; `decode_token` enforces the expected token type.
- settings auto-detect algorithm from key shape (PEM→RS256 else HS256) and derive the public key from the private RSA key when absent — observable: an HS256 secret works with `public_key == private_key`; a PEM private key auto-selects RS256 and extracts the public key.
- `mwt_obtain` mints an MWT from the authenticated session via `create_mwt`, requiring `MIZAN_MWT_SECRET`, and `jwt_obtain`/`jwt_refresh` issue/rotate the JWT pair carrying user claims — observable: `mwt_obtain` on an anonymous request raises; with no secret configured it raises a clear config error; the JWT pair includes `is_staff`/`is_superuser` so downstream auth needs no DB query.

---

## Unit: mizan-django registration & export (`backends/mizan-django/src/mizan/export`, `.../management`, `.../setup`, `.../__init__.py`, `.../urls.py`, `.../_vendor`)

**Charter.** The Django discovery/registration glue and the two protocol export surfaces: the Edge manifest generator and the KDL IR management command, plus URL wiring, session-init, and the ASGI/channels wrapper. It owns clients.py auto-discovery and the manifest/IR export commands; it delegates registry and IR shape to `mizan_core`.

**Claims substantiated here.**
- Codegen IR export (KDL) via `python manage.py export_mizan_ir` (backends/mizan-django/README.md; docs/AFI_ARCHITECTURE.md § Forward-direction primitives).
- Edge manifest export, deterministic (sorted) output; both RPC and view-path functions; records each context's `render_strategy` (ROADMAP.md § Done; docs/PSR_VS_EDGE.md; ISSUES.md § Resolved — edge manifest non-determinism fixed).
- Function discovery / registration via the clients.py convention (backends/mizan-django/README.md § Setup; MIZAN.md §6).
- PSR (`render_strategy` in manifest) (docs/PSR_VS_EDGE.md).
- Session / CSRF init endpoint; `wrap_asgi` WebSocket routing (backends/mizan-django/README.md § Setup).

**Owed behavioral mechanisms.**
- `export_mizan_ir` populates the registry via discovery, then writes canonical KDL from `mizan_core.ir.build_ir` — observable: the Django-emitted KDL is byte-identical to the FastAPI and Rust emissions for the same fixture (`tests/afi/test_codegen_parity.py`); this is the "IR is the only contract, validated against multiple adapters" claim made checkable.
- `generate_edge_manifest` emits a deterministic (sorted contexts and mutations) JSON mapping contexts to endpoints/params/functions, distinguishing rpc vs view path, marking `user_scoped` and `render_strategy` (`dynamic_cached` for user-scoped, `psr` for public), and mutations with auto-scoped params + private/route — observable: two exports are byte-identical regardless of registration order; a context with `user_id` is `user_scoped`+`dynamic_cached`; a view-path function's `route` populates `page_routes`; a mutation whose args match context params lists them under `auto_scoped_params`.
- `mizan_clients` discovers `ServerFunction` subclasses under each app's `clients.py`/`clients/` layer and registers them idempotently — observable: re-running discovery does not double-register; a class already registered under a different name is skipped rather than clobbered.
- the session-init view sets the CSRF cookie and returns the token, and `wrap_asgi` routes `/ws/` to the channels consumer — observable: `GET /session/` returns `{csrfToken}` and a `Set-Cookie: csrftoken=…`, so SSR/clients can establish CSRF before an authenticated call; `wrap_asgi(get_asgi_application())` produces a ProtocolTypeRouter dispatching http vs websocket.

---

## Unit: mizan-django protocol tests (`backends/mizan-django/src/mizan/tests` — test_core.py, test_auth.py, test_ssr.py, test_benchmarks.py)

**Charter.** The Django backend's protocol-and-integration verification: the executor/registry/invalidation/merge/cache/manifest/edge-compatibility/auth/SSR/throughput suites. It holds the evidence that the dispatch, invalidation, cache, auth, and SSR mechanisms above behave as claimed against the real HTTP stack; it authors no production mechanism.

**Claims substantiated here.**
- The dispatch, invalidation, merge, cache, auth, and SSR claims of the mizan-django dispatch/cache/ssr/jwt sub-units are *verified* here; the "passes its own test suites" status rests on this harness.
- Edge caching is provable before Edge exists — deterministic JSON, correct Cache-Control, header round-trip, auth-differentiated responses (test_core.py § EdgeCompatibilityTests, an explicit doc-shaped claim carried in the suite).

**Owed behavioral mechanisms.**
- the suite exercises the real HTTP stack (Django test client / LiveServer) — not just RequestFactory — for dispatch, three-tier invalidation, merge, view-path branching, and cache HIT/MISS/scoped-purge — observable: `HTTPIntegrationTests` and `CacheIntegrationTests` assert the JSON body and `X-Mizan-Invalidate` header agree, that a scoped mutation preserves other users' cached entries, and that a second identical fetch is a HIT.
- the auth suite covers every axis (JWT valid/invalid/expired, MWT, session, staff/superuser/callable/PermissionError) and asserts the body never runs on failure — observable: an invalid token returns 401 without session fall-through; an anonymous call to an auth-required function returns before the body; a callable's `PermissionError` message surfaces verbatim.
- the Edge-compatibility suite asserts the properties a CDN cares about (deterministic byte-identical bodies, sorted JSON keys, URL-encoded delimiter-safe headers, `no-store` on errors/mutations, header↔body invalidation agreement, auth-differentiated responses for the same URL) — observable: these tests go red if any of those properties regress, so "Edge caching is possible" is checkable without a CDN.
- the SSR suite verifies the engine-based render path — template-backend resolution, bundle-driven in-process render, the hydration wrapper, and concurrent renders — and asserts that no external JS runtime process is spawned during the suite (the PyO3-bound `SsrEngine` renders in-process) — observable: a render produces the `<div id="mizan-root">` + `__MIZAN_SSR_DATA__` wrapper from the resolved bundle, concurrent renders across worker threads each use their own engine and return correct results, and the suite spawns no `bun`/`node` subprocess. The Bun ping / crash-recovery / auto-restart assertions are retired with the subprocess bridge they exercised; today `test_ssr.py` still drives `SSRBridge` (Bun subprocess, JSON-RPC, killed-worker restart), so this engine-path verification is owed alongside the mizan-django SSR PyO3 cutover.
- the benchmark suite measures HTTP-vs-executor overhead and throughput with correctness assertions on each path — observable: every benchmark also asserts the function's numeric output, so a green benchmark run is also a correctness run.

---

## Unit: mizan-django adversarial & feature tests (`backends/mizan-django/src/mizan/tests` — test_pentest.py, test_security.py, test_channels.py, test_shapes.py)

**Charter.** The Django backend's adversarial and feature-specific verification: the penetration/security suites (attacker-shaped defenses) and the channels/shapes suites (feature behavior). It holds the evidence that validation, authorization, channel subscription, and shape diffing behave as claimed against hostile and edge inputs; it authors no production mechanism.

**Claims substantiated here.**
- The auth-guard, input-validation, and no-info-disclosure claims (INVARIANTS.md § Auth; executor validation) are verified adversarially here.
- The WebSocket channel authorization/subscription and API Shapes diff/query claims (INVARIANTS.md § WebSocket Support, § API Shapes) are verified here.

**Owed behavioral mechanisms.**
- the pentest and security suites assert the properties an attacker probes: validation-runs-before-execution, private/internal functions unreachable over RPC, no sensitive detail in production error messages, injection strings (SQL/command/template/prototype-pollution/unicode-lookalike/zero-width) treated as inert data, and no function-existence timing leak — observable: these tests go red if the executor ever runs a body before validation, leaks a secret in a 500, or executes an injection payload.
- the channels suite verifies subscription lifecycle and authorization: param validation before `authorize`, `authorize`-false and `authorize`-raise both blocking cleanly, duplicate-subscription rejection, room-level per-param authorization, and WS-RPC gated to `websocket=True` functions — observable: subscribing to a room the user cannot access is rejected; an RPC to an HTTP-only function returns FORBIDDEN over the socket.
- the shapes suite verifies query efficiency and diff correctness across the hard cases: single-query flat, prefetch nested (no N+1), UUID/slug/int PKs, two-FKs-to-same-model, self-referential and nullable FKs, `False`/`0`/`""` treated as present, batched `diff_many`, and strict nested-diff access raising on typos — observable: a nested query asserts exactly the prefetch count; a mistyped nested-diff name raises rather than silently returning empty.

---

## Unit: mizan-fastapi (`backends/mizan-fastapi/src/mizan_fastapi`)

**Charter.** The FastAPI adapter targeting the AFI-common subset: RPC dispatch, context bundling, JSON-body invalidation + merge, auth gating, the error envelope, and the KDL IR CLI. It owns the FastAPI transport surface over `mizan_core`; Forms/Channels/Shapes/SSR are explicitly out of scope.

**Claims substantiated here.**
- RPC call dispatch, named-context bundle fetch, JSON-body invalidation, three-tier auto-scoping, function registration, KDL IR export (README.md § Adapters; backends/mizan-fastapi/README.md).
- Auth-guard enforcement (`auth=` rejects) (backends/mizan-fastapi/README.md § Auth integration).
- The same core primitives as Django, proving the protocol is not Django-specific; IR-shape parity with Django and Rust (README.md § Conformance; docs/AFI_ARCHITECTURE.md).
- Every error path renders through the Mizan envelope; `GET /session/` returns a null CSRF token for wire parity (backends/mizan-fastapi/README.md § Setup; README.md § Adapters note 7).

**Owed behavioral mechanisms.**
- `execute_function` looks up the registered function, enforces `auth` before running (matching Django's semantics: `True`/`required`/`staff`/`superuser`/callable), validates input against the Pydantic `Input`, awaits `view.acall` (async handlers on the loop, sync in a threadpool), and serializes via `jsonable_encoder` — observable: an anonymous call to `@client(auth=True)` returns 401 before the body; an `async def` handler runs on the loop (a real `await` inside completes); `list[BaseModel]`/`Optional[BaseModel]` reach the wire bare.
- `compute_invalidation` auto-scopes by matching args against the context's declared Input fields, emitting a bare context or a `{context, params}` object — observable: a mutation with a matching arg emits the scoped form, a non-matching arg the bare context string; identical to the Django resolver's output.
- `compute_merges` resolves the slot by unique return-type match (`types_match_for_merge`) and emits `{context, slot, value, params?}`, dropping ambiguous — observable: the `morph_groups`/`morph_layers` fixture routes a `MorphLayer` mutation to `morph_layers` only; a merge-only mutation emits `merge` with empty `invalidate`.
- the router exposes `POST /call/`, `GET /ctx/{name}/`, `GET /session/` and both exception handlers render every failure through `{"error":{code,message,details?}}` with `Cache-Control: no-store` — observable: an unknown function returns 404 in the envelope; a malformed body returns `BAD_REQUEST`; a validation failure returns 422; `/session/` returns `{csrfToken: null}` (parity, since CSRF is Django-only).
- `python -m mizan_fastapi.ir <module>` imports the module (triggering registration) and writes canonical KDL — observable: its output equals the Django management command's output for the same fixture (three-way parity).

---

## Unit: mizan-rust-axum (`backends/mizan-rust-axum`)

**Charter.** The Rust/Axum HTTP adapter: the `/call/`, `/ctx/:name/`, `/session/` handlers, the error envelope, and app-state threading, dispatching through `mizan-core`'s `FUNCTIONS` registry. It owns the Axum wire surface; dispatch/invalidation/merge logic is `mizan-core`.

**Claims substantiated here.**
- RPC call dispatch, named-context bundle fetch, JSON-body invalidation, three-tier auto-scoping, KDL IR export (README.md § Adapters; note 6).
- Axum error envelope mirrors FastAPI's with `Cache-Control: no-store` (backends/mizan-rust-axum/src/errors.rs).
- Query params are coerced to typed JSON via the per-function input params (handlers.rs).

**Owed behavioral mechanisms.**
- `function_call` dispatches through `lookup_function` + `FunctionSpec::dispatch`, then attaches `compute_invalidation` and `compute_merges` output, mirroring the FastAPI response shape `{result, invalidate, merge?}` — observable: the wire-parity drivers (`tests/rust/drive_kernel.rs`, `drive_emitted.rs`) run the same probes against the Axum server and FastAPI and require the same JSON shapes and invalidate/merge semantics.
- `context_fetch` bundles every registered member of the context and coerces string query params to typed JSON via each function's `input_params` primitive table — observable: `GET /ctx/user/?user_id=5` returns the flat bundle with `user_id` coerced to an integer before dispatch; an unknown context returns the envelope 404.
- app state is type-erased into the handle and downcast in user functions — observable: a handler downcasts `RequestHandle` to the concrete state type; the stateless router variant threads a unit handle.
- OWED (unbuilt caveats, README.md § Caveat + notes 2,3,5): Axum declares `Transport::Websocket` in the IR/macro but routes no WebSocket handler; carries `is_form`/`form_role` trait stubs but no validate/submit endpoint; and accepts `auth=` on a function but the dispatch path does not enforce it — observable: a `websocket=True` function is reachable only over HTTP; an `auth=True` function is NOT rejected for anonymous callers on this adapter. These are documented gaps the "auth enforced on every adapter" invariant (INVARIANTS.md § Auth) owes and Rust/Axum does not yet meet.

---

## Unit: mizan-tauri (`backends/mizan-tauri`)

**Charter.** The Tauri adapter: a plugin exposing a single `mizan_invoke` command that routes op-tagged call/fetch envelopes through the shared `mizan-core` registry over Tauri IPC. It owns the IPC wire surface; dispatch/invalidation/merge are `mizan-core`.

**Claims substantiated here.**
- RPC call dispatch, named-context bundle fetch, invalidation (JSON body only), three-tier auto-scoping (README.md § Adapters; note 1).
- Transport is Tauri IPC (a single `#[tauri::command]` envelope), not HTTP; invalidation rides the response body; no header channel (README.md note 1; backends/mizan-tauri/README.md § Wire protocol).
- `RequestHandle` wraps `AppHandle` so functions can access managed state; `Result<T, MizanError>` supported (backends/mizan-tauri/README.md § App-state access).

**Owed behavioral mechanisms.**
- the plugin registers exactly one command (`plugin:mizan|mizan_invoke`) that deserializes the op-tagged envelope and dispatches `call`/`fetch` through the same `FUNCTIONS`/`CONTEXTS` slices the HTTP adapter uses — observable: `{op:"call", fn, args}` returns `{result, invalidate, merge?}` and `{op:"fetch", context, params}` returns the flat bundle, identical shapes to the axum adapter minus the header channel; there is no per-function `#[tauri::command]`.
- errors flow through Tauri's reject path re-wrapped into the `{code, message, details?}` shape — observable: a `MizanError::ValidationFailed` reaches the JS transport as the same envelope an HTTP 422 would carry, so consumer error handling is transport-agnostic.
- `RequestHandle::new(app)` lets a function downcast to `tauri::AppHandle` for managed state / event emission — observable: a function calling `req.downcast::<tauri::AppHandle>()` reaches Tauri state; stateless functions ignore the handle.
- OWED (unbuilt caveat, README.md § Caveat + note 5): Tauri's `FunctionSpec` carries `auth`/`private` fields but the dispatch path does not enforce them — observable: an `auth=`-declared function is not rejected for an unauthorized caller on this adapter; the "auth enforced on every adapter" invariant is not yet met here.

---

## Unit: mizan-rust client kernel (`frontends/mizan-rust`)

**Charter.** The Rust port of the shared client kernel: the reconciled cache (context registry + state), transport (HTTP with retry, CSRF), merge splicing, the debounced invalidation queue, error-envelope parsing, and the PyO3 bridge that exposes the kernel to Python. It owns the client-side reconciled view; framework rendering lives in adapters.

**Claims substantiated here.**
- The client kernel owns the reconciled cache — context state, status, error, server-driven merge and invalidate, session init — reached through a pluggable transport; no adapter keeps its own copy of the truth (INVARIANTS.md § Client Kernel; docs/AFI_ARCHITECTURE.md § Kernel model).
- Mutation invalidation auto-refetches affected contexts; on failure nothing invalidates (INVARIANTS.md § Mutation Invalidation).
- Merge splices the return value into the cached entry rather than refetching (the `merge=` path; MIZAN.md §5 fresh-return optimization generalized).
- Transports are pluggable (HTTP, Tauri IPC, webview) via `configure` (docs/AFI_ARCHITECTURE.md § Kernel model; frontends/mizan-tauri-transport/README.md).
- The Python client is a typed facade over this kernel via PyO3 (protocol/mizan-codegen python target; baselines/python/client.py).

**Owed behavioral mechanisms.**
- the context registry keys entries by context name + `stable_key(params)`, holds one `ContextState {data, status, error}` per entry, and notifies subscribers via a watch channel that coalesces to the latest state — observable: `stable_key({b,a})` == `stable_key({a,b})` (byte-identical to `JSON.stringify` with sorted keys), so the same params hit the same cache entry regardless of key order; a refetch advances the entry through Loading→Success visible to subscribers.
- `mizan_call` applies the response's `merge` entries first, then queues `invalidate` entries, then returns `result` — observable: a mutation response `{result, merge, invalidate}` splices the merged slot into the cached bundle AND schedules refetch; a failed call (4xx) surfaces the error and invalidates nothing.
- `splice_slot` upserts by `id` into an array slot, replaces an array slot with a new array, replaces a scalar, and no-ops a merge into a slot absent from the bundle — observable: merging `{id:1,name:"A"}` into `[{id:1,…},{id:2,…}]` replaces entry 1 in place; merging into a missing slot leaves the bundle untouched (no fabricated slot on a stale cache).
- the invalidation queue debounces within one async tick, and broad invalidations subsume scoped ones for the same context — observable: two invalidations queued in the same tick flush once; a broad invalidate refetches every param variant while a scoped invalidate refetches only the matching entry.
- transport is HTTP-with-retry (3 attempts, linear backoff, retry on 5xx/network, surface 4xx immediately), reads the CSRF cookie into the configured header per call, and is swappable — observable: a 5xx retries then errors; a 4xx returns immediately; swapping the transport (Tauri/webview) leaves the generated call/fetch code unchanged (transport read from config).
- the error envelope parses both the FastAPI nested shape and the Django flat shape, falling back to `HTTP_<status>` — observable: `{"error":{"code":…}}` and `{"error":true,"code":…}` both yield the correct `code`; an unparseable body yields `HTTP_500` with the raw body.
- the PyO3 bridge exposes `call`/`fetch_context`/`subscribe_context`/`invalidate` with the GIL released across the network round-trip, and fires the Python subscription callback on each watch change with a `{data,status,error}` dict — observable: `py.allow_threads` wraps the blocking call; a subscription callback fires with `status: "success"` and the decoded data; cancelling ends the watcher.

---

## Unit: mizan-base and framework adapters (`frontends/mizan-base`, `frontends/mizan-react`, `frontends/mizan-vue`, `frontends/mizan-svelte`)

**Charter.** The TypeScript client kernel (`@mizan/base`) and the per-framework idiomatic adapters (React hooks, Vue composables, Svelte stores) that subscribe to it. `@mizan/base` is the authoritative kernel the `frontends/mizan-rust` unit ports; the TS source is referenced by the docs and adapters but is not inlined in this repo snapshot. Listed so the kernel claims and the adapter-parity claims are surfaced against their real roots. The `mizan-ts` cross-language HMAC pin (`deriveCacheKey`) also lives on the TS side.

**Claims substantiated here.**
- Every frontend adapter is a thin idiomatic wrapper over one shared kernel; the kernel owns `ContextState<T> = {data,status,error}`, `registerContext`, `mizanCall`/`mizanFetch`, server-driven merge/invalidate, `initSession`, and a pluggable `MizanTransport` (HTTP default, Tauri/webview swap via `configure`) (INVARIANTS.md § Client Kernel; docs/AFI_ARCHITECTURE.md § Kernel model).
- Shared parameters elevate to required provider props; non-shared params elevate to optional props with per-function override (INVARIANTS.md § Named Contexts; MIZAN.md §2 param elevation / `specify` resolution order).
- Codegen targets the adapter surface, never the raw kernel; React devs get hooks, Vue composables, Svelte stores, same kernel underneath (docs/AFI_ARCHITECTURE.md § Kernel model).
- Vue and Svelte ship as v1 alongside React (docs/AFI_ARCHITECTURE.md § Launch surface).
- Cross-language HMAC pin: `deriveCacheKey` in `mizan-ts` matches the Python key byte-for-byte (docs/CACHE_KEYING.md; README.md § Adapters — TypeScript is the protocol-reference adapter).

**Owed behavioral mechanisms.**
- `@mizan/base` owns the single reconciled view: `ContextState`, the context registry, `mizanCall`/`mizanFetch`, server-driven `merge`/`invalidate`, `initSession`, over a `MizanTransport` interface — observable: the same behaviors the `mizan-rust` port pins (stable-key cache identity, merge-splice, scoped-vs-broad refetch, retry, dual-envelope error parse) hold in TS; the Rust port exists precisely to mirror this file.
- the generated provider elevates a context's shared params to required props and its non-shared params to optional props, and resolves each member's effective params by overlaying per-function overrides onto the provider props at fetch time (INVARIANTS.md § Named Contexts; MIZAN.md §2 resolution order) — observable: a two-function `user` context where both take `user_id` and only one takes `page` generates a provider with required `user_id` and optional `page`; a per-function override supplies a different `page` for that one member while the shared `user_id` still covers both, and a member still missing a required param at fetch time is a runtime error, not a silent undefined.
- `deriveCacheKey` (mizan-ts) reproduces the Python HMAC key byte-for-byte — observable: the pinned vectors in `cores/mizan-python/tests/test_keys.py::test_cross_language_pin` (`ctx:user:605a1ca5…`, `ctx:user:30fc08eb…`) are asserted against the TS output; any normalization drift (bool/None stringification, key ordering) breaks the pin, which the doc marks a security vulnerability.
- adapters subscribe to the kernel and render in their own idiom without keeping a parallel copy of the truth — observable: a React hook and a Vue composable over the same context read the same kernel entry; mutating in one path updates both because the truth lives once in the kernel.
- OWED (unbuilt, ISSUES.md § Open / ROADMAP.md § Next): `frontends/mizan-vue` and `frontends/mizan-svelte` are runtime kernel-adapter packages — the codegen emits their clients (byte-parity-tested) but no runtime package or live-backend example exists — observable when built: a Vue composable / Svelte store subscribes to `@mizan/base` and refreshes on invalidation against a live backend; today only React has full integration verification, so the "Vue and Svelte ship as v1" claim is unsubstantiated at the runtime layer.
- OWED (drift, ISSUES.md § Open): the Svelte codegen target emits Svelte 4 `readable` stores; Svelte 5 `$state`/`$derived` runes are owed — observable when built: the emitted Svelte client uses runes.
- OWED (migration, ISSUES.md § Open): `mizan-react/src/context.tsx` is the pre-kernel provider still shipped and imported by the desktop example, coexisting with the codegen-emitted kernel-subscribing `MizanContext`; retiring it (migrating the example onto the generated provider) is owed so the "every adapter wraps the kernel, none keeps its own truth" invariant holds without exception.

---

## Unit: mizan-codegen (`protocol/mizan-codegen`)

**Charter.** The single Rust codegen binary that reads KDL IR and emits typed clients for every target (stage1, react, vue, svelte, channels, python, rust), plus the source-fetching that spawns each backend's IR-export command and the Pydantic-pre-step, plus the SSR bundling step that compiles each SSR entry component into a self-contained render bundle. It owns the IR→client transform and the SSR bundle production; it does not emit IR (backends do) or run the render engine (that is `cores/mizan-rust-ssr`).

**Claims substantiated here.**
- Codegen reads KDL directly — no OpenAPI envelope, no `openapi-typescript`, no per-backend converter; the former JS two-stage codegen is deleted (docs/AFI_ARCHITECTURE.md § Forward-direction primitives).
- Every frontend client is generated from the IR; each target is byte-parity-tested (INVARIANTS.md § Canonical IR & Codegen; ROADMAP.md § Rust codegen).
- The codegen drives the backend's IR-export command as a subprocess and parses the KDL it writes (docs/AFI_ARCHITECTURE.md; backends/*/README.md § Generate the frontend).
- Stage 1 (typed `callXxx`/`fetchXxx`) + Stage 2 (`<MizanContext>` provider, per-context providers, `use{Hook}()`) emission (backends/*/README.md § Generate the frontend).
- Pydantic + Rust DX: a decoru pre-step authors Rust types from Pydantic before the cargo IR bin runs; a generic `[source.script]` source spawns any command emitting KDL (backends/mizan-tauri/README.md § Pydantic; config.rs).
- mizan-generate's SSR bundling step compiles each SSR entry component together with `react-dom/server.browser` into a self-contained bundle assigning `globalThis.renderApp`, written to the `bundles` directory — the only place node/bun run in the SSR path (docs/SSR_ARCHITECTURE.md § The engine; § AFI boundary — Build step row).

**Owed behavioral mechanisms.**
- `fetch.rs` spawns the configured source's export command (FastAPI `-m mizan_fastapi.ir`, Django `manage.py export_mizan_ir`, Rust `cargo run --bin`, or a generic script) and parses stdout as KDL — no OpenAPI/converter anywhere in the path — observable: a codegen run against a live FastAPI backend consumes only the KDL the CLI writes; the Rust source runs the cargo bin and the optional decoru pre-step first.
- the KDL parser reconstructs the full typed IR (types with struct/list/enum/alias shapes, functions with input/output/nullable/context/affects/merge/form, contexts with param elevation, channels) — observable: `ir_deserialization.rs` reads the AFI fixture back into typed structs and asserts the function set, per-function fields, param elevation, and named-type presence.
- each target emits deterministically and is byte-parity-tested against a committed baseline — observable: `stage1_parity.rs`, `react_parity.rs`, `rust_parity.rs`, `python_parity.rs`, `vue_svelte_parity.rs`, and `channels_smoke.rs` diff emitter output against baselines and fail on any byte drift; two different runs produce identical output.
- the emitters produce genuinely different, correct artifacts per target — not one shape behind distinct labels — observable: the react target emits `<MizanContext>` + per-context providers + `use{Hook}()` reading React context (Stage 2), Stage 1 emits the framework-agnostic typed `callXxx`/`fetchXxx`; vue emits composables; svelte emits stores; python emits a Pydantic-typed facade over the PyO3 kernel; rust emits a full crate depending on `mizan-rust` — each byte-checked against its own baseline, and stage1 is auto-included whenever a framework target is requested.
- the codegen tree-shakes and canonicalizes types to match the backend emitters, and hoists inline enums into named Rust/TS types — observable: an unreferenced type is not emitted; an inline `field { enum … }` becomes a top-level Rust enum the struct field references; the channels target emits zero files when the IR carries no channels.
- OWED (unbuilt): an SSR bundling step compiles each SSR entry component together with `react-dom/server.browser` into a self-contained bundle that assigns `globalThis.renderApp`, emitted into the configured `bundles` directory — this is the only place node/bun run in the SSR path — observable when built: a `mizan-generate` run produces one render bundle per SSR entry component, each evaluable standalone by the embedded-V8 engine (assigning `renderApp` at eval time and rendering from a JSON-parsed props argument). Today the codegen binary emits typed clients (stage1/react/vue/svelte/channels/python/rust) but carries no SSR bundling target in `src/emit/` and no bundling path in `fetch.rs`/`config.rs`, so the bundling step the docs place with `mizan-generate` is unsubstantiated.
## Unit: AFI conformance (`tests/afi`)

**Charter.** The cross-adapter conformance gate: one fixture registered identically in Django, FastAPI, and a Rust app, asserting all three emit byte-identical KDL. It is the executable form of "the IR is the only contract"; it authors no production mechanism.

**Claims substantiated here.**
- Adapter parity is gated by the AFI conformance suite asserting IR-shape parity — the same fixture through Django, FastAPI, and Rust emits byte-identical KDL (README.md § Conformance; docs/AFI_ARCHITECTURE.md § KDL is the IR — "divergence between adapters is what the IR exists to prevent").

**Owed behavioral mechanisms.**
- one shared fixture (`fixture.py` and its Rust twin `rust_app`) registers the same 7 functions / 5 types / context+affects+merge graph across all three backends, and the parity test diffs the three KDL emissions requiring exact three-way equality — observable: `test_codegen_parity.py` fails (naming the divergent pair) the instant any adapter's type introspection, ordering, or param elevation drifts; the fixture spans the AFI axes (plain fn, no-input fn, shared-param context, affects mutation, optional return, merge mutation) so the gate is not a degenerate single-shape check.

---

## Unit: wire-parity drivers (`tests/rust`, `tests/rust/fixture_client`)

**Charter.** The runtime wire-contract gate: Rust drivers (`drive_kernel`, `drive_emitted`) that hit a live FastAPI fixture and a live Rust/Axum fixture and assert the same JSON shapes and invalidate/merge semantics, plus the codegen-emitted `fixture_client` crate they exercise. It proves the runtime wire equivalence the static IR parity does not, and authors no production mechanism.

**Claims substantiated here.**
- The Rust adapters honor the same wire contract as FastAPI beyond static IR equivalence — same JSON shapes, same invalidate/merge semantics (README.md § Adapters; the "IR prevents divergence" claim taken to the runtime).
- The codegen-emitted typed client round-trips cleanly through the kernel (protocol/mizan-codegen rust target).

**Owed behavioral mechanisms.**
- `run_wire_parity.py` boots each backend, probes the readiness surface `/api/mizan/session/` (Mizan-protocol-shaped, so the harness reads the same surface across backends), then runs both the raw-kernel and emitted-typed drivers against each, propagating any non-zero exit — observable: the drivers hit every fixture endpoint (plain functions, the two-function context, the optional-return path, the merge mutation) against both FastAPI and Rust/Axum and require the same responses; a wire drift on either backend turns the harness red.
- `drive_emitted` exercises the codegen-emitted `fixture_client` typed functions (`call_echo`, `fetch_user_context`, `call_update_profile`, the optional `call_find_user`, the merge `call_rename_user`) so the generated crate is proven to round-trip, not merely to compile — observable: `call_find_user(99999)` returns `None`, `fetch_user_context(5)` returns the bundled `user_profile`+`user_orders`, and any deserialization mismatch fails the driver.
