diff --git a/docs/AFI_ARCHITECTURE.md b/docs/AFI_ARCHITECTURE.md index d29dbc2..a9ffee9 100644 --- a/docs/AFI_ARCHITECTURE.md +++ b/docs/AFI_ARCHITECTURE.md @@ -38,12 +38,34 @@ against the raw kernel — so a React developer gets `useEcho()` and ``, a Vue developer gets `useEcho()` composables, a Svelte developer gets readable stores. Same kernel underneath. -## Schema is load-bearing +## KDL is the IR -The backend exports a JSON schema describing every `@client`-decorated -function and context (`x-mizan-functions`, `x-mizan-contexts`). The -schema IS the contract: codegen reads it, the edge manifest derives -from it, MWT auth gates against it. +The Mizan IR is **KDL** — the LLVM-IR-equivalent of the system. Every +backend adapter produces KDL describing its registered functions, +contexts, types, and invalidation graph. Every codegen target consumes +KDL. KDL is the contract; everything else (REST envelopes, OpenAPI +documents, framework idioms) is sediment around it. + +The IR must be validated against multiple adapters before it is +considered stable. Single-adapter validation hides assumptions — +divergence between adapters is what the IR exists to prevent. + +Forward-direction primitives: + +- `cores/mizan-python` builds the IR from registered functions + (`build_ir()` walks `mizan_core.registry`, emits KDL) +- A `mizan-schema` package (forthcoming) holds the canonical KDL + grammar / type system definition that every adapter targets +- Codegen reads KDL directly — no OpenAPI envelope, no + `openapi-typescript`, no per-backend converter divergence +- Edge manifest, MWT claims, and other protocol artifacts all derive + from the same KDL + +**Current implementation is transitional.** Today the codegen consumes +OpenAPI 3.0 (`x-mizan-functions` + `x-mizan-contexts` extensions over +Pydantic→JSON-Schema), produced via Django Ninja or FastAPI's native +generator. That layered indirection is what introduces adapter +divergence (see the AFI conformance suite). KDL-as-IR collapses it. ## Launch surface