FreedomLang

Model the world as data. Treat bugs as fatal.

FreedomLang is a small AOT-compiled systems language for auditable native tools.

It draws one hard line:

missing file       -> world state
network timeout    -> world state
permission denied  -> world state

bad tag
bad field access
impossible state   -> fatal bug

External uncertainty belongs in data. Broken invariants do not.

FreedomLang is not trying to replace Rust, Go, Python, or shell. It is for the narrow places where you want a native binary, explicit failure semantics, and a compiler/runtime that a determined engineer can read end to end.

No more magic. Reality is magic enough.

In three sentences: FreedomLang compiles .flx source through a JavaScript compiler and a compact IR into native x86-64 artifacts. It draws a hard semantic line between external uncertainty, which is modeled as explicit data, and broken program invariants, which terminate immediately. The project is pre-1.0, but the compiler, runtime model, backends, and behavior tests are real enough to evaluate from code instead of promises.

In one paragraph: FreedomLang is a deliberately small, readable compiler/runtime stack for people who care about native tools, auditability, and failure semantics more than optimizer sophistication or ecosystem size. Programs use familiar imperative syntax, user-defined operators, object-shaped calls, tagged runtime values, explicit job/fork concurrency, and a growing chaos/world-state model for things like missing files and network timeouts. The compiler does not rely on LLVM, a VM, or a JIT; the repository contains the frontend, IR lowering, platform backends, runtime helpers, stdlib, and behavior suite, so public technical questions can usually be answered by pointing at a source file or test.

What it is

FreedomLang is an AOT compiled language with a compiler written as ordinary JavaScript. There is no project-specific compiler binary to install in the normal workflow: you run freelang.js with Node.js, inspect the compiler source in this repository, and get native x86-64 output.

The current pipeline is:

.flx source -> lexer/parser -> AST -> FreedomLang IR -> x86-64 backend

Targets today:

Target	Output
Linux x86-64	Direct native ELF executable
macOS x86-64	Native assembly linked by clang into Mach-O
Windows x86-64	Native x86-64 assembly for the Microsoft ABI, linked into PE/COFF with LLVM/MSVC tools

The Linux icon is the Ubuntu mark because CI currently runs on Ubuntu-hosted Linux; the target is Linux x86-64 generally, not Ubuntu-only.

The implementation entry point is freelang.js. The major compiler pieces live in src/frontend.js, src/ir.js, src/backend/, and src/runtime/.

Why it exists

FreedomLang is built around a simple rule:

Model the world as data. Treat bugs as fatal.

Network timeouts, missing files, EOF, and permission failures are world states that code should model explicitly. Invalid tags, impossible states, bad field access, and broken invariants are bugs; they should stop the job instead of leaking into later computation.

That gives FreedomLang its main benefits:

• Auditability: the compiler and runtime are intentionally small and direct.
• Predictability: no user exceptions and no hidden recovery paths.
• Native artifacts: generated programs run as x86-64 binaries or linked assembly, not on a VM or JIT.
• Explicit runtime model: tagged values, visible heap object layouts, runtime checks, and fail-fast traps.
• Isolation-oriented concurrency: jobs use explicit handles and wait; modern fork blocks make concurrency visible in source.

No more magic

Reality is magic enough.

Modern software has been living through an age of magic.

Magic render trees. Magic object queries. Magic deployment layers. Magic async behavior. Magic recovery paths. Magic defaults. Magic frameworks that look like the thing you already know, but are subtly not that thing, until your expectations become the bug.

Enough.

No more cursed magic.
No more magic footguns.
No more hidden recovery paths.
No more exception mazes.
No more framework seances.
No more "trust me" runtime behavior.
No more clever layers silently doing the expensive thing you did not ask for.

FreedomLang is built from the opposite instinct.

Do not hide the world. Model it.

A missing file is not an exception from reality. It is reality.
A network timeout is not a surprise. It is the network.
Permission denied is not a stack trace waiting to happen. It is a world state.

Those states should be visible in the program.

missing file       -> world state
network timeout    -> world state
permission denied  -> world state

bad tag
bad field access
impossible state   -> fatal bug

The line matters.

External uncertainty belongs in data. Broken invariants do not.

FreedomLang does not try to make every failure recoverable. It tries to separate the failures you must model from the bugs you must stop.

If a program depends on the world, the world should be in the program.

If a job forks, the fork should be visible.
If a job waits, the wait should be visible.
If data crosses a boundary, the boundary should be visible.
If the program enters an impossible state, it should die there, loudly, before the lie spreads.

FreedomLang is early. It does not fully achieve this philosophy yet. But this is the direction of the work:

No more magic. Reality is magic enough.

Feature domains

Status key: ✅ implemented and covered, 🟡 implemented but still hardening or platform-gated, 🧭 planned or aspirational.

Pain points addressed

Advantages and limits

FreedomLang's current advantages are practical, not magical: small inspectable implementation, native artifacts, explicit world-state handling, runtime bounds/shape checks, custom operators, and observable FSABI concurrency. The strongest security-oriented claim is reduced and more visible trusted code, not immunity from bugs.

Do not read "no libc" as "no legacy risk anywhere." It means generated programs do not bring in a C runtime by default in the current backend paths; the OS, linker, system DLLs/frameworks, and FreedomLang runtime helpers still matter. Do not read "AI-friendly" as "AI-proof"; it means the language is being shaped around explicit control flow, explicit world modeling, and testable boundaries.

Aspirations

These are goals, not launch claims:

• Stable no-heap/no-GC profile for programs that do not allocate heap objects.
• Linux and Windows parity for chaos, filesystem, and TCP surfaces.
• Exec/process APIs after network parity.
• Versioned safety profile with enforceable restrictions.
• Better diagnostics, editor support, examples, and agent-oriented debugging workflows.

Current status

FreedomLang is early, real, and pre-1.0.

What works today:

• Integers, strings, arrays, objects, bytes, variables, blocks, loops, and control flow.
• User operators, including positional, object-shaped, scalar infix, shaped infix, and value-shape overloads.
• Runtime-checked array/object access and fatal diagnostics for invalid states.
• Native x86-64 backends for Linux, macOS, and Windows.
• Explicit job concurrency with fork blocks, handles, wait, and blocking fork sugar lowered through real child jobs.
• FSABI job directories and essential inbox/outbox parameter paths across Linux, macOS, and Windows.
• A shared behavior test suite with expected stdout/stderr/exit-code files.
• Heap support across all backends, with GC behavior still being hardened to parity.
• Experimental chaos/world-state syntax and stdlib surfaces, strongest on macOS.

What is still moving:

• The language and stdlib APIs are not stable.
• Chaos/network surfaces are actively evolving and platform-gated.
• Exec/process APIs are planned after network parity work.
• Documentation is intentionally focused on current specs, tutorials, and implementation guides; use docs/INDEX.md as the map.
• The safety-profile work is drafted but not complete.

Current implementation and test matrix:

Platform	Category	Implementation status	Test status
Linux x86-64	Native output	Direct ELF executable emitted by the JavaScript backend	Green in CI
Linux x86-64	Core language/runtime	Integers, strings, arrays, objects, bytes, operators, control flow, checks	Covered by shared behavior suite
Linux x86-64	Heap/GC	Heap allocation works; the direct ELF path currently uses mmap-backed allocation rather than the parity collector path	Allocation behavior covered; GC parity wiring remains open
Linux x86-64	Fork/FSABI	Child jobs, job directories, blocking fork sugar, inbox/outbox essentials	Parity-essential tests green
Linux x86-64	Chaos/files/net	Some chaos/files/net surfaces are platform-gated while parity advances	Not yet treated as full release parity
macOS x86-64	Native output	Native assembly linked by clang into Mach-O	Green in CI
macOS x86-64	Core language/runtime	Same shared IR and runtime model as other targets	Covered by shared behavior suite
macOS x86-64	Heap/GC	Generated conservative heap/GC path is emitted when heap features are used	GC stress and behavior tests green
macOS x86-64	Fork/FSABI	Blocking fork lowers to real child jobs with FSABI directories and outbox reads	Parity-essential tests green
macOS x86-64	Chaos/files/net	Strongest current implementation for chaos, file, and TCP surfaces	Platform-gated chaos/net tests green
Windows x86-64	Native output	Native x86-64 assembly for the Microsoft ABI, linked into PE/COFF through LLVM/lld	Green in CI
Windows x86-64	Core language/runtime	Shared IR lowered to Windows calling convention and runtime helpers	Covered by shared behavior suite
Windows x86-64	Heap/GC	Windows GC is generated; long stress behavior is still being hardened	Enabled GC tests green; redundant deep stress cases are skipped pending hardening
Windows x86-64	Fork/FSABI	CreateProcess-backed child jobs and FSABI job directories	Parity-essential tests green
Windows x86-64	Chaos/files/net	Some chaos/files/net surfaces remain platform-gated	Not yet treated as full release parity

Programs that do not allocate heap objects should not need heap initialization or GC work on the hot path, and the backends already feature-gate much of that emission. A fully explicit no-heap/no-GC profile is still a planned release surface, not a stable command-line promise.

Syntax shape

FreedomLang syntax is intentionally small but not especially mainstream. The main shapes are:

Comparison to other languages

FreedomLang is not trying to win a general-purpose language bakeoff. It is a focused experiment in small native tools, explicit world-state handling, and readable compiler/runtime implementation.

The syntax has prior-art echoes rather than a single ancestor: Unix job control and process isolation, result-value error handling, object-shaped calls, indexed slot access, and explicit tagged world states. Expect it to feel alien at first; the bet is that unusual syntax is acceptable if it makes operational boundaries and failure behavior easier to audit.

Language genealogy

This is a relationship map, not a claim that FreedomLang descends directly from any one language. The project combines several older ideas in a deliberately small AOT compiler.

FreedomLang
├─ C / Zig / Go family
│  ├─ AOT compilation to native artifacts
│  ├─ operational tools as a serious target
│  └─ explicit release binaries instead of a VM or JIT
├─ Unix process model and shell job control
│  ├─ fork blocks
│  ├─ wait points
│  └─ filesystem-visible job inbox/outbox state through FSABI
├─ ML / Rust Result / tagged-union thinking
│  ├─ external world states represented as explicit values
│  └─ recoverable outcomes separated from bugs
├─ Erlang-style fault-boundary intuition
│  ├─ jobs as failure boundaries
│  └─ fatal invariants handled by containment, not local exception recovery
├─ JavaScript/object-record ergonomics
│  ├─ object-shaped calls
│  └─ field-oriented runtime shapes
├─ Operator-rich languages
│  ├─ custom positional and object-shaped operators
│  └─ infix and value-shape overloads for domain notation
└─ Agent-readable implementation practice
   ├─ compiler distributed as Node.js-readable JavaScript source
   ├─ behavior tests as executable claims
   └─ explicit effects, waits, and fatal paths for debugging

The unusual part is the combination: AOT native output, a compiler you run as Node.js source, custom operator syntax, explicit chaos/world-state modeling, and FSABI job concurrency in one small stack. None of that makes FreedomLang mature by itself; it makes the project easier to inspect and argue about from code.

Quick start

Requirements:

• Node.js 22 or newer for the compiler.
• clang for macOS/Windows linking workflows.
• On macOS, the test runner uses gtimeout from Homebrew coreutils if available or installs it when needed.
• On Windows, install LLVM and a Windows SDK containing kernel32.lib; the PowerShell runner discovers the SDK library path and links with lld.

Compile a Linux ELF directly:

node freelang.js hello.flx hello.bin --target=linux --emit=bin
./hello.bin

Compile macOS assembly and link it:

node freelang.js hello.flx hello.s --target=darwin --emit=asm
clang -target x86_64-apple-macos12 -nostdlib -Wl,-e,_main -Wl,-static hello.s -o hello.bin
./hello.bin

Compile Windows assembly:

node freelang.js hello.flx hello.s --target=windows --emit=asm

Or compile, link, and run with the helper:

pwsh ./flx.ps1 hello.flx

Small example

op sum3 [a, b, c] (
  => a + b + c;
)

let values = [2, 3, 5];
let total = sum3 [values\0, values\1, values\2];

if (total == 10) (
  print "ok";
) else (
  fall "unexpected total";
)

Object-shaped operators bind by field name. String/array/object + overloads are provided by f/operators:

credits: <f/operators>;

op describe {name, role} (
  print "user: " + name + " (" + role + ")";
)

describe {role: "admin", name: "alice"};

Modern fork blocks make job creation explicit:

let job = ( (
  print "child";
  => 42;
) )&

let answer = wait job;
print answer;

Blocking fork sugar runs the child as an actual job, waits, and reads the named outbox value:

let answer <= (
  (
    let child_value = 42;
    child_value >value;
    => 0;
  )
)&

print answer;

Testing

Run the Unix/macOS suite:

bash tests/run-all.sh --hide-passes > test-output-current.txt 2>&1

Run the Windows suite:

pwsh ./tests/run-all.ps1 -HidePasses > test-output-windows.txt 2>&1

The test system is behavior-driven. A tests/foo.flx program can be paired with:

• foo.expect.exit
• foo.expect.out
• foo.expect.err
• unordered stdout/stderr variants for concurrent output

See tests/README.md and tools/compare-run-output.js.

Repository map

Documentation

Start here:

• docs/INDEX.md - map of the current docs.
• docs/spec/FreedomLang-Specification.md - language specification draft.
• docs/tutorials/Tutorial.md - hands-on tutorial.
• docs/chaos-world-model.md - world-state vs bug model.
• docs/spec/fsabi-concurrency-spec.md - FSABI concurrency specification.
• docs/FSABI_IMPLEMENTATION_GUIDE.md - backend/runtime implementation guide for FSABI paths.
• docs/spec/freelang-power-of-ten-profile.md - draft safety profile.

Release posture

FreedomLang is suitable today for:

• reading and evaluating the implementation,
• experiments with small native tools,
• internal prototypes,
• language/runtime design review,
• security-oriented discussions about failure semantics and auditability.

It is not yet a stable production language distribution. Treat public releases as evaluation builds until the compiler flags, stdlib APIs, platform support, and safety profile are versioned and locked.

License and contact

FreedomLang is dual-licensed: AGPL-3.0-or-later for open-source use, or a separate commercial license from DO-SAY-GO Corporation for uses that are not compatible with the AGPL.

The source license does not grant trademark rights. See TRADEMARKS.md.

Security contact: security@freelang.dev