HbcModule · ABI hbc0Compiler stack
One source-language pipeline, two compiled products.
Hara source is read into spanned forms, normalized through namespace configuration, compiled into one validated bytecode program, and encoded as HBC. Whole-Wasm is built from that canonical HBC program rather than from a second source-language compiler.
.hal → spanned Forms → validated Program → HBC hbc0 → VM or Whole Wasm hnw0/2 WholeWasm · ABI hnw0/2Pipeline
Compilation starts with source-positioned forms.
The compiler reads source with parser spans intact. Multiple top-level forms are treated as an implicit do. Namespace declarations are prepared before lowering, then aliases and exclusions are rewritten against the selected namespace configuration.
01 · Reader
Source becomes SpannedForm trees.
compile_source calls the Hara reader and keeps source positions attached to the form tree. Diagnostics, source maps, and later validation therefore refer back to the original source rather than a text round trip.
02 · Namespace configuration
Aliases are resolved before bytecode lowering.
ns and ns+ clauses produce a generated namespace configuration. The compiler rewrites forms against that configuration and synchronizes aliases with the runtime registry when compiling inside an existing session.
03 · Bytecode compiler
Forms lower directly into instructions and function prototypes.
Lexical scopes, captures, loops, exception handlers, constants, globals, calls, destructuring and supported language forms are lowered into a Program. Unsupported language forms produce typed compile errors. They are not converted into fallback evaluator calls.
04 · Validation
The Program is checked before it becomes an artifact.
The compiler finalizes source maps, validates bytecode structure and stack behaviour, and retains function/schema information used by runtime and conformance tooling.
Canonical product
HBC is the compiler's first durable artifact.
The standalone compiler facade exposes CompileTarget::HbcModule. It compiles source to a validated program, encodes that program, and wraps the bytes in an immutable compiled-product manifest whose product kind is HbcModule and ABI is hbc0.
HBC can execute in the VM-only runtime without requiring the whole-Wasm compiler.
HBC route
HbcModule · hbc0
Use this product when the host already provides the Hara bytecode VM. It is compact, deterministic, portable across VM hosts, and is the canonical program retained by higher-level compiled products.
- Input
.halsource- Product
HbcModule- ABI
hbc0- Execution
- Hara VM
Whole-Wasm route
WholeWasm · hnw0/2
The whole-Wasm target first produces the same HBC bytes, then packages the canonical program into the versioned whole-Wasm artifact. Decoding a whole-Wasm product yields the program whose re-encoded HBC matches the original HBC module.
- Input
- canonical HBC
- Product
WholeWasm- ABI
hnw0/2- Execution
- Whole-Wasm host
Product identity
Compiled outputs are content-addressed build products.
Every compiler product records the source digest, compiler identity, ABI version, target kind, output bytes and the digest of its canonical HBC module input. The compiler cache key uses the same inputs, so two identical compilations can reuse the same immutable product rather than relying on process-local source state.
Source entry point
compile_source
Reads ordinary Hara source, prepares namespaces, lowers supported forms and produces a validated VM program.
Registry-aware entry point
compile_source_with
Compiles against an existing namespace registry so already interned vars and runtime aliases are visible to the compiler in the same form they will have at execution.
Configured entry point
compile_source_with_config
Accepts an already resolved namespace configuration and applies source-positioned rewrites before lowering. Runtime sessions use this when namespace metadata has already been loaded.
HALC entry point
compile_halc_module
Consumes decoded HALC directly. It removes the namespace declaration from executable code, preserves schema-definition and function-schema graphs on the resulting program, infers function types, and validates declared arities.
Evaluator boundary
The compiler and evaluator are separate execution strategies.
Hara still has tree-evaluation surfaces for interactive and semantic runtime operations. The bytecode compiler does not use that evaluator as an escape hatch. A form that is outside the supported compiled language reports a compile error instead of emitting a structural-evaluation opcode or text round trip.
Hara source compiler
.hal source → HBC → whole-Wasm
This path owns Hara-language semantics. The durable semantic program is HBC, and whole-Wasm packages that program for a Wasm execution host.
Foreign-Wasm bindgen
library.wasm + interface.hal → binding package
This sibling pipeline does not compile the foreign library from Hara source. It structurally inspects existing Wasm bytes and uses a semantic interface to generate core.v1, memory.v1, or hta.v1 package metadata and optional adapters.
Example
Keep source examples independent of a private compiler command.
The checked-in compiler-stack example contains ordinary Hara source plus a product map. The public compiler API currently lives in the Rust compiler crate and browser runtime APIs; this guide intentionally does not invent a CLI command that the repository does not expose.