How codurralabs/nebulara works
1. What this repo is
Nebulara is a language platform, not a single app: it contains the language grammar, compiler pipeline, native runtime/JIT, a VM layer, standard libraries, and a few higher-level domain modules. The core architectural boundary is between NBS source modules (.nbs) and the native/runtime execution stack implemented in C and JavaScript.
2. Language front end
The front end lives in Grammar/ and Parser/. Grammar/grammar.nbs and Grammar/enhanced-grammar.nbs define the language shape, while Parser/lexer-core.nbs, Parser/lexer.nbs, Parser/parser-core.nbs turn source into structured program data. This is the first major flow: source text → tokens → parsed syntax tree / intermediate form.
3. Compiler pipeline
Compiler/ contains the transformation stages: semantic.nbs for validation and resolution, ir-ssa.nbs for intermediate representation, transpiler.nbs plus transpiler-js.nbs and transpiler-py.nbs for target emission, and binary-emitter.nbs / x86-binary.nbs for machine-code output. Compiler/bootcompiler.nbs and Compiler/nbs-bootstrap.c indicate a bootstrap path for compiling the compiler itself.
4. Code generation targets
The compiler is multi-target. One path produces native x86 output for the in-repo JIT/runtime, and other paths emit JavaScript or Python. That means the architecture is split between a native backend and source-to-source transpilers, with shared front-end semantics feeding both.
5. Runtime and native execution
Runtime/ is the execution boundary. nbs_cli.c, nbs_jit.c, nbs_loader.c, and nbs_x64.c handle command-line execution, JIT compilation, and module loading. Runtime/nbs_loader.h is the shared interface, and Runtime/node_loader.js provides a Node-based loader path. In the current repo state, the readme says the 32-bit x86 JIT is working while x64 is incomplete.
6. Virtual machine layer
VM/bootstrap.nbs, VM/nrunner.nbs, and VM/nvm-vm.nbs form a VM-oriented execution model separate from the native JIT. The architecture therefore has two execution abstractions: a native JIT/runtime path and a VM/bootstrap path for module execution and experimentation.
7. Standard library and core services
std/ provides language-level primitives and utility modules: collections, JSON, network, time, strings, primitives, and kanban. Lib/ adds lower-level integration and math/IO helpers, plus FFI and adapter layers. This is the boundary where language code gets access to common runtime services without embedding those concerns in the compiler.
8. Foreign-function and host adapters
The C adapters in Lib/ (cpp-adapter.c, nodejs-adapter.c, python-adapter.c) plus NBS-side FFI modules (Lib/ffi.nbs, Lib/nadapter.nbs, transport/ffi.nbs) define host interoperability. Lib/vulkan.nbs and Lib/nvulkan.nbs show planned or partial GPU integration. Architecturally, this is the escape hatch from Nebulara into native libraries and external runtimes.
9. Transport and IPC
transport/ipc.nbs and transport/ffi.nbs separate inter-process communication from in-process FFI. That implies a runtime boundary between local module calls and cross-process integration, likely used by loaders, orchestrators, or host tooling.
10. Higher-level application layer
aurora/ and knowledge/ are not core language infrastructure; they look like an AI/knowledge application layer built on top of Nebulara. aurora/events.nbs, aurora/gateway.nbs, and aurora/orchestrator.nbs suggest event-driven orchestration, while knowledge/store.nbs suggests an embedded knowledge store. These modules sit above the compiler/runtime stack and consume the language as a platform.
11. Packages and configuration
Packages/BUILD.nbs and Packages/config.nbs indicate a package/build abstraction inside the ecosystem. Combined with configure, configure.nbs, build.nbs, Makefile, and build.bat, the repo supports multiple build entrypoints and bootstrap modes, with the native toolchain currently centered on MinGW-w64 per the readme.
12. Verification, release, and legacy surface
Tests are split between test/hello.nbs and tests/nebulara.test.ts, showing both language-level and host-level validation. GitHub workflows handle release and SLSA publishing. v1/ is a legacy packaging surface, while docs/, SPEC.md, and ARCHITECTURE.md are the design contract for the system.
Main entry points: collections.nbs Std lib · ir-ssa.nbs IR SSA · nbs_loader.c Loader · ffi.nbs FFI
Components 18
Language front end
Grammar and parsing from source text into structured syntax.
Compiler pipeline
Semantic analysis, IR, transpilation, and native emission.
- Semantic · Validates and resolves program meaning before code generation.
Compiler/semantic.nbs - IR SSA · Compiler intermediate representation and SSA-like lowering.
Compiler/ir-ssa.nbs - Transpilers · Source-to-source emission for JavaScript and Python targets.
Compiler/transpiler.nbs - Native emit · Binary emission for native execution and JIT paths.
Compiler/binary-emitter.nbs - Bootstrap · Bootstrap compiler path and native bootstrap bridge.
Compiler/bootcompiler.nbs
Execution stack
Native runtime, loader, JIT, and VM/bootstrap execution paths.
- CLI · Command-line entry for launching Nebulara programs.
Runtime/nbs_cli.c - Loader · Loads modules and mediates runtime module access.
Runtime/nbs_loader.c - JIT · Native execution and JIT compilation path.
Runtime/nbs_jit.c - VM · VM/bootstrap execution model separate from native JIT.
VM/nvm-vm.nbs - Builtins · Core runtime builtins exposed to language code.
Runtime/builtins.nbs
Libraries and interop
Standard library, FFI, host adapters, and transport boundaries.
- Std lib · Collections, JSON, networking, strings, time, and primitives.
std/collections.nbs - FFI · Foreign-function bridge into host libraries and adapters.
Lib/ffi.nbs - Adapters · C-side adapters for Node.js, Python, and native interop.
Lib/nodejs-adapter.c - Transport · IPC and transport boundary separate from in-process calls.
transport/ipc.nbs
Connections 20
- Grammar → Parser: defines syntax · Grammar feeds the parsing pipeline.
- Parser → Semantic: AST / IR · Parsed structures move into semantic validation.
- Semantic → IR SSA: lowering · Validated programs are lowered into compiler IR.
- IR SSA → Transpilers: emit source · IR can be emitted to JavaScript and Python targets.
- IR SSA → Native emit: emit native · IR can be lowered to native binary output.
- Bootstrap → Native emit: bootstraps · Bootstrap path supports compiling compiler/runtime pieces.
- Native emit → JIT: feeds code · Native output is used by the runtime/JIT path.
- CLI → Loader: starts · CLI invokes module loading and runtime setup.
- Loader → Builtins: exposes · Loader wires builtin runtime services into execution.
- Loader → JIT: loads for · Loader prepares code for native execution.
- JIT → VM: alternative path · VM layer represents a separate execution model.
- Builtins → Std lib: supports · Builtins back standard library functionality.
- Std lib → FFI: escapes to host · Standard libraries can call into host interop.
- FFI → Adapters: bridges · FFI uses host-specific adapters and bindings.
- FFI → Transport: cross-process · Transport handles IPC-style integration boundaries.
- Transport → Aurora: orchestrates · Higher-level modules use transport for coordination.
- Transport → Knowledge: persists · Knowledge modules can be built on transport-backed services.
- VM → Aurora: runs modules · Aurora can execute through VM/bootstrap paths.
- Std lib → Aurora: uses · Application modules depend on standard library services.
- Std lib → Knowledge: uses · Knowledge layer relies on shared library services.