Files
ziran/docs/ARCHITECTURE.md
waozi 9432a11070
Alpha check / check (push) Failing after 17m32s
Reserve native frame storage only while instances execute
Keep checked pointer slots persistent and reserve the full frame arena for
an active outermost invocation, including reentrant callbacks. Release it
on return or trap so idle bundles fit in a 32-bit address space.

Add a bounded address-space regression with eight independent native
instances, precise loader diagnostics, and runtime documentation.

Validation: make check (272/274), then passing focused rechecks for the
repaired diagnostic registry and generated architecture page; bootstrap
verification; exact ARMv7 Moto Lumi/Practice, navbar, and PiP tests.
2026-11-19 14:00:28 -03:00

2.5 KiB

Ziran architecture

Ziran owns the language, compiler, standard library and executable runtime. Applications own product code; Kryon owns UI widgets and rendering.

Compiler pipeline

Source → ZIR → LIR → optimized LIR → ZX → native (ELF/PE, x86-64/AArch64/ARMv7). WebAssembly lowers from verified ZX through zx2wasm. C and Go export from ZIR through zi2c and zi2go.

The frontend checks imports, types, expressions, laws and ownership rules before writing .zir. The linker includes reachable code, lowers to LIR, verifies and optimizes it, and writes verified ZX instructions. The native backend consumes those instructions and applies CPU lowering and platform ABI services. ziran build FILE.zi selects native output by default. zx2native --emit elf writes ELF on Linux and PE32+ on Windows; supported CPU/platform combinations and service limits are diagnosed by the selected backend.

ziran run uses native execution on Linux x86-64, AArch64 and ARMv7. The instruction engine can be selected explicitly with --backend engine on zi2zx run. A failed native lowering does not retry on another engine. Browser execution uses the Wasm tier. See ZX.

Native instances retain globals, heap and checked pointer slots between calls. Temporary frame storage lives only during an active outermost invocation, including its reentrant host callbacks, and is released on return or trap. Idle instances do not reserve the frame limit, keeping multiple bundles usable in a 32-bit address space. The full limit and pointer lifetime checks still apply during execution.

Safety and capabilities

Safety is manual by default. --checks enables build-wide runtime checking; #checks retains bounds checks for a selected region. The instruction engine always checks. See the guide.

Host capabilities describe typed services required by linked code. Host bindings implement them; CPU instruction lowering and ABI veneers implement the machine target. A missing binding or unsupported instruction is an error. Programs without graphical imports run without a graphical host.

Shared checked representation

C and Go exporters consume the same checked ZIR model. All routes must preserve observable language behavior within their supported subset. Contexts own parsed declarations, interned text, source spans and scratch storage. Linked programs retain contexts whose data they borrow. See compiler embedding for lifetime and concurrency rules.