From 19ce4d4a2a98abebfe8984fb87bf45370c3cca01 Mon Sep 17 00:00:00 2001 From: Ryth Azhur Date: Thu, 7 May 2026 23:19:40 -0400 Subject: [PATCH] Restore KDL-as-IR to AFI_ARCHITECTURE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-stating the architectural intent that got silently swapped to "JSON schema" during the doc-restoration commit (6eca514). The original AFI_ARCHITECTURE positioned KDL as the LLVM-IR-equivalent of the system; I read the stale-package-name note at the bottom as invalidating the whole architecture description and substituted JSON-schema references thinking that was the more-current intent. That conflated implementation drift (mizan-ast/mizan-schema package names) with substrate intent (KDL is the IR). The packages had drifted; the IR target had not. Restoring the section. Frames KDL-as-IR explicitly as forward-direction. The current OpenAPI/JSON-Schema codegen path is transitional — it's the layered indirection where adapter divergence lives (AFI conformance suite demonstrates this). Real KDL implementation lives in a forthcoming mizan-schema package; today's path is sediment around the eventual substrate. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/AFI_ARCHITECTURE.md | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) 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