The file roles are .zi for source, .zir for checked intermediate modules,
and .zx for portable executables. The portable tool is zi2zx, and its
target name is zx. A .zx file is revision-28 executable ZX: verified
lowered instructions, the program's assets and the names its embedder sees.
The normative byte contract is
the executable format specification; see
Implementation status for the remaining work.
Running bundles
Run source in one command: ziran run hello.zi or zi2zx run hello.zi. Both
check the file, write the bundle in memory and execute its main; its folder
is the default module root. ziran run app.zx and zi2zx run app.zx run a
bundle file. Zero-argument entries returning an integer, bool or nothing
run; the command prints a non-void result on its own line, unsigned results
over their full range.
On Linux x86-64, AArch64 and ARMv7, ziran run app.zx, zi2zx run and the embedding API run a
bundle as native code compiled from its verified instructions; in a browser
it runs on the Wasm tier and on other CPUs on the portable instruction engine.
The platform makes that choice, never the bundle: a bundle native code cannot
run fails before it starts with a named gap. --backend engine picks the
engine explicitly. Native code follows manual safety like C: a pointer is its
address and indexes are raw, and each run of allocate gets fresh zeroed
storage that lasts until its frame returns. A bundle built with --checks
(header flag 1 of its instructions) checks every pointer as the engine does:
a read through a pointer into a returned frame, a use after free, a second
free, a store through read-only bytes and an index out of range all trap.
#checks marks single instructions to keep their bounds check in a bundle
built without it. The engine always checks. A native trap is reported once. Nothing ever falls back to, or retries on, the
engine. zi2zx --debug also writes
the program's source origins to the optional debug attachment, so native trap
diagnostics and zx2native --emit map name source lines.
Compiled native code is cached on disk in $XDG_CACHE_HOME/ziran/native, or
~/.cache/ziran/native without it, so a later run in another process maps the
code instead of compiling it again. An entry is keyed by the bundle's content,
the CPU's features and the build of the compiler that made it. It is checked
against that key and its SHA-256 digest before it is used, and a damaged entry
is removed and rebuilt. ZIRAN_NATIVE_CACHE=DIR uses another directory and
ZIRAN_NATIVE_CACHE=off turns the cache off.
Learning
ziran build FILE.zi keeps a corpus of the programs it compiles to native code,
as training data for improving Ziran's machine code. It is on by default,
ziran learn off stops it and ziran learn on resumes it; benchmarks run
through bench/bench.zi never record. Recording never prints during a build;
ziran learn status reports a record that failed. Each new build stores its verified
.zx, ELF, zx2native --emit map ranges and lowered input once under
$XDG_DATA_HOME/ziran/learn (or ~/.local/share/ziran/learn), named by their
SHA-256 digests, so a rebuild writes nothing and a compiler that emits different
code adds a second record beside the first. Programs are filed by format,
zx<R>-lir<S>/<ZX sha256>/, from the bundle's own header revision and
instruction schema: tools read only their own revision, so a format change
starts a new folder instead of mixing in programs the current tools reject.
Each record ends with <target>-<ELF sha256>.record.json, written last, which
names the compiler (the SHA-256 of zx2native and zi2zx and the Ziran
version), the source and entry and the Unix time. --limit-mb N caps the
corpus (1024 MB by default), ziran learn status shows its size and each
format's programs and records, ZIRAN_LEARN=on|off overrides the switch and
ZIRAN_LEARN_DIR=DIR moves the corpus.
ziran learn verify --candidates FILE --repo DIR --output FILE validates the
C teacher's closed integer rewrite proposals against generated C, boundary and
deterministic random inputs, and the retained parity fixtures. A disagreement
leaves the table unchanged. bench/bench.zi -- c-teacher produces the assembly
comparison, sampled rankings and candidate files.
ziran learn train --measurements FILE --table FILE --verification FILE
--output FILE selects implemented policies from paired timing receipts joined
to current-format corpus artifacts. It checks the compiler, ZX, ELF and native
map identities, equal C/native checksums, learning-off measurements, common
host and source epoch. It retains symmetric 1.5×IQR filtering and deterministic
size/policy tie breaking. Unsupported unroll and allocation choices are refused.
Review the generated source table, rebuild and run parity before checking it in.
Normal builds use only the versioned table in cmd/compiler_learning_table.zi;
recording and offline training never change a running compiler's policy.
Use ziran run app.zx for both console and graphical programs. The linker
includes the reachable code of imported modules, including a UI library.
Platform effects such as windows and input are supplied by an installed runtime
provider. Ziran discovers providers generically, without UI-library names or
widget-specific startup behavior. A console bundle with no required host
capabilities runs directly and never starts a graphical provider.
Packages install a .host registration containing one absolute executable path
under share/ziran/hosts. Discovery searches $XDG_DATA_HOME/ziran/hosts
(default $HOME/.local/share/ziran/hosts), then each $XDG_DATA_DIRS entry
(default /usr/local/share:/usr/share). Registrations are tried in filename
order within each directory. ZIRAN_HOST_PATH overrides these locations with
colon-separated absolute registry directories; empty and relative entries are
ignored. Bundle directories and embedded assets are never provider search roots.
A provider implements --check FILE.zx, returning zero only when it can supply
all required capabilities. Checking must not execute application initializers
or entries or open a window. The selected executable then receives FILE.zx.
Its exit status is the run status; an execution failure never retries the app
on another provider. Malformed bundles fail before discovery. Missing providers
produce a diagnostic before the application executes. Provider registration is
part of the library platform installation and adds no requirement to a
console-only Ziran install.
For example, Kryon make install-user installs its reusable desktop provider.
A graphical .zx then runs with ziran run app.zx without application sources,
a manifest or generated native output. The portable bundle carries its linked
UI code and embedded assets; the installed provider bridges the local OS.
Writing bundles
zi2zx --root DIR [--module-path DIR] [--define NAME] [--asset-dir NAME=DIR] [--retain module:function] [--bind caller:capability=provider:function] [--bind-host MODULE] --entry module:function -o FILE file.zi|file.zir ...
loads explicit inputs and their extensionless imports, lowers what the entry
reaches to instructions, verifies and optimizes them, and writes the bundle.
Source and saved .zir give the same file:
zi2zx --root src --entry app:main -o app.zx src/app.zi
zx2native --target x86_64 --platform linux --emit elf -o app app.zx
zi2zx run app.zx
zi2zx --emit lir -o - app.zx
zx2wasm -o app.wasm app.zx
The required program section holds deterministic verified lowered
instructions, stripped of source names and instruction origins. A procedure's
#asm variants are lowered from its portable body, so a bundle holds no
machine code of its own. Native output from source serializes and reads this
same verified ZX boundary; source and ZX entry routes produce identical ELF
bytes. --opt --emit lir and --opt --emit opt-report inspect the pre-ZX
optimization stage; ZX input is never reoptimized.
Reading a bundle validates section framing, SHA-256 content identities, the instruction decoding, the verifier, the entry identity and the reachable symbol and capability set before anything runs. The input bytes may be released after the read. A file of another revision is rejected; there is no fallback reader. An edited program byte fails the identity check.
Reachable #foreign host_api calls become host capabilities, called by
host.call. A bundle may instead bind one such call to an exported Ziran
function among its input modules with --bind; the bound call runs inside the
same instance and is absent from the capability list. The optional host
interface section names, for each capability, the type spellings and record
field names of its parameters and result, its declaration as written, the
program's module globals and the entry's signature: what an embedder sees and
the instruction payload does not keep. Every global of the entry module is
named, read or not; another module's globals are named when the program
reaches them. A record may hold itself through a slice. A bundle whose
interface cannot be written fails with assembly.container instead.
Embedding
An embedding C host links build/libziran.a, includes ziran_host.h, and opens
a bundle with BundleOpen or BundleOpenBytes (OpenBundle and
OpenBundleBytes in std/bundle_host). It lists the required capabilities
with BundleCapabilityCount, BundleCapabilityModule and
BundleCapabilityFunction, and passes HostBinding entries to BundleRun or
BundleInstantiate. Every required capability needs exactly one binding before
any initializer or entry runs; missing or duplicate bindings fail first.
Instantiation copies the binding names and indexes them, so caller order does
not matter. Separate instances of one bundle may run concurrently; each owns its
globals, which persist across BundleInstanceRun calls. Global initializers run
when the instance opens.
Each host call is translated between the engine's host image and HostValue
trees by the host interface section. A value's type is the spelling declared at
its position, and a spelling that starts with u is unsigned; a u64 above the
s64 range reaches the host in bits alone. Returned records give every
declared field by name and in order, unless BundleInstanceMatchFieldsByName
lets a host built against another layout omit or add fields. Numeric, string
and record slice parameters cross as HOST_SLICE with a mutable elements
array: the host keeps the count and pointer, and its changes are validated and
copied back into the caller's slice after a successful call. Two slice
arguments of one call may not share elements. Declared pointer types cross as
HOST_POINTER: an opaque handle that bundles store, compare and pass back,
and that fails the run when the program reads through it. The host owns the
storage behind every handle it hands out. A value that nests past 64 levels,
such as a tree that holds itself, fails the call. Values a host returns are
copied into the instance, which gives their storage back once nothing the
program can reach names them.
A run is not bounded: like the program's native builds, it continues until the
entry returns. BundleInstantiateLimited(bundle, bindings, count, max_steps)
gives one positive step budget to global initialization and every entry run,
so a runaway initializer fails instantiation; BundleInstanceLimitSteps
bounds each later run on its own. Steps are function calls and loop
iterations. A runaway recursion stops with "nested calls filled the stack";
other run failures name what happened, such as an index out of bounds or
unreachable code executed, and the instruction where it did.
Target contract
The pipeline is Source → ZIR → LIR → optimized LIR → ZX → native
(ELF/PE, x86-64/AArch64/ARMv7). Wasm lowers from ZX; C/Go export
from ZIR through zi2c/zi2go.
The portable instruction engine runs the instructions on any platform. A
supported direct target lowers the same verified instructions to machine code,
applies the target ABI and platform veneers, and writes a platform binary;
zx2native --target x86_64 --platform linux --emit elf is the Linux x86-64 row, and
--platform windows writes the Windows x86-64 row's PE32+ .exe. Generated C and Go are
separate routes, never native fallback. A Linux x86-64 executable links its
host capabilities by name from the registered host libraries, with the C ABI
the C target declares for them (host capabilities);
a capability none defines is the assembly.gap.machine-host gap.
The linker includes reachable code from ordinary libraries, Kryon only when
the program imports it. A non-UI command-line program is a first-class .zx;
it launches without a graphical host. Kryon UI code is portable Ziran code in
the bundle, with rendering and input supplied through declared host
capabilities. A portable bundle cannot contain an undeclared dependency on
target-specific C or Go code. Host capabilities name portable typed services
and are bound independently of CPU lowering; missing host bindings and missing
ABI veneers are different gaps and neither is repaired by the other layer.
Component identity, state, and replacement
A component is an ordinary .zx entry plus its declared host capabilities;
Ziran has no UI- or application-specific component names. BundleCodeIdentity
returns the SHA-256 of the bundle's bytes, and BundleEntryModuleName and
BundleEntryFunctionName expose the entry identity. BundleCapabilityAbiAt
returns each capability's module, function, declaration, argument and return
text, varargs flag and argument-read flag. BundleAbiCompatible requires the
same entry identity and signature and the same capability ABI set in both
directions.
BundleComponentOpen retains the bundle, copies the host bindings, and creates
one independently initialized instance with a positive step budget. Handles
become stale when their generation is replaced or their component closes, and
running a stale handle fails without touching the current instance.
BundleInstanceExportState snapshots the module globals the interface section
names as recursive BundleStateValue data, by module, name and declared type.
Strings, fixed arrays, records, enums and vectors are deep-copied; pointers,
procedure values, slices and other borrowed or host resources are rejected.
Snapshots are bounded in depth and by 16 MiB of copied payload, which
BundleStateValueBytes reports. A migration callback receives the old snapshot and a mutable snapshot
of the replacement's initialized state, then BundleInstanceImportState
converts every value before changing any global.
BundleComponentReplace is transactional. It checks the ABI, initializes the
replacement under the component budget, exports both states, migrates and
imports, and calls the optional verification callback while the old instance
remains live. Only when every step passes does it close the old instance and
advance the handle generation; any failure leaves the previous instance and
bundle live. BundleComponentLiveValueBytes reports the instance's global and
owned value storage, not shared code, host allocations or process RSS.
tests/bundle_step_limit.sh covers migration, every rollback, stale handles and
typed-ABI rejection.
WebAssembly execution tier
A host that installs a WebAssembly provider with ZxWasmSetPlatform
(cmd/zir/zir_zx_wasm_platform.h) runs bundles as WebAssembly:
BundleInstantiate lowers the bundle's verified program with the engine's
Wasm lowering, instantiates it through the provider, runs its module
initializers, and charges the run budget like the instruction engine. An
Emscripten build of libziran installs the browser provider itself. In an
Asyncify runtime, whose hosts may suspend the stack, modules are lowered
suspendable (LowerProgramSuspendable): a module unwinds with the stack
and resumes at the host call when it rewinds. A JSPI runtime leaves bundles to the
instruction engine. Set ZIRAN_WASM_TIER=0 in the environment, or
globalThis.ZIRAN_WASM_TIER = "0" before a page loads the runtime, to leave
bundles to the instruction engine. Each instance
keeps its own bindings and linear memory. Host calls and module state cross as
host images, which the embedding API translates to HostValue trees by the
host interface section, so typed capabilities, records, strings, slices and
state export and import behave as on the engine. A program outside the
lowering, or a module the provider rejects, fails instantiation; no other
engine starts. A web build needs libziran built with the instruction engine,
that is without BOOTSTRAP=1. tests/zx_wasm.sh runs bundles on the tier
under node beside the engine, and tests/zx_web_lifecycle.sh runs source
through .zx in a private headless Chromium.
zx2wasm lowers the same verified ZX to one wasm32 module, and
ziran build --target=wasm runs it; source and saved-ZX input give identical
bytes. The module imports zx.overrun and the mutable zx.budget global that
every fuel instruction charges. zx2wasm --unbounded makes the module for a
run with no step budget, as a native executable is: its fuel instructions
charge nothing and it imports no zx.budget. A module imports zx.host_i64
when the program prints and zx.host when it calls a host capability. It
exports zx_entry, memory, zx_initialize when it has module initializers
and zx_reserve when it has a heap; a zxhost custom section names each
capability. A form it has no code
for stops at a named wasm.gap.* diagnostic. The host-call record layout is in
cmd/compiler_zx_wasm.zi.
Embedded files and application hosts
--define NAME selects the same source branches as the native compiler.
--asset-dir assets=assets embeds regular files recursively under assets/.
The argument's left side is the path prefix inside the bundle, and its right
side is the source directory or file. Multiple mappings may be supplied.
Names are sorted bytewise for deterministic output. Duplicate names, symlinks,
absolute paths, backslashes, empty components, and . or .. components are
rejected. The asset section is part of the bundle's content identity.
BundleAssetCount, BundleAssetName, BundleAssetData and BundleAssetSize
expose the immutable files until BundleClose; std/bundle_host wraps them
for Ziran hosts. Opening a bundle needs no temporary files.
Kryon's reusable desktop player supplies rendering and input to a ZX instance;
the application's widgets and state run inside it. A downloaded graphical
program launches with ziran run app.zx after the desktop provider is
installed, including embedded images. See
Kryon project profiles.
Application-specific storage, audio, and other native interfaces still require
declared host capabilities with portable signatures.