A programming language written by someone who has watched too much anime and not enough sleep, but somehow it compiles.

---

What is FREAK?

FREAK is a compiled, statically-typed systems language with a syntax inspired by visual novels, anime, and the kind of programming that only makes sense at 3am.

It compiles to native binaries via LLVM (or C — your choice). It has a Phase-1 borrow checker behind --strict-borrow. It has a package manager called Hangar and preserves the COCKPIT UI source preview for Maverick. And every variable is called pilot because you are always on a mission.

pilot name = "Takeru"
pilot power = 9001

task greet(name: word) -> void {
    say "Hello, {name}! Your power level is {power}."
}

greet(name)

That's it. That's the whole vibe.

---

Release 0.15.1: read the release notes. Upgrading from 0.14.2? Read the 0.15.0 breaking changes first.

Features

The Language

• pilot — variables. You are assigning a pilot to a mission.
• task — functions. Everything is a task.
• give back — return. Because return is cowardly.
• say — print. Always available. No imports.
• when — pattern matching over literal values.
• fixed pilot — immutable binding. The pilot cannot be reassigned.
• trust me — unsafe blocks, Python bootstrap only (not in shipping V3). You asked for this.
• training arc — bounded loop with a session cap. Compiles to a counted while.
• eventually — block that runs at the end of the current scope.
• isekai — nested scope with explicit bringing back { ... } exports (Python bootstrap; not in shipping V3).

Native extern task names beginning with __freak_ are reserved for compiler output, and source tasks cannot redeclare compiler builtin call names. V3 rejects both cases before C or LLVM emission so user symbols cannot collide with the packaged runtime ABI.

The Type System

Type	What it is
num	64-bit float. The default. Context-narrows to int.
int	64-bit signed integer.
word	UTF-8 string. Fat pointer. Knows its own length.
bool	Booleans. true/false/yes/no/hai/iie are all valid literals.
List<T>	Typed lists: new / with_capacity / filled, push / pop / clear / reserve, capacity / length, indexing, for each.

The Python bootstrap additionally understands maybe<T>, result<T, E>, and Map<K,V>; those reach the self-hosted compiler with V4.

The bible promises a wider type universe — mood, prob[lo..hi], power<N>, tiny, uint, char, big, float32, fixed [T;N], tuples, raw pointers. Those ship with the V4 self-hosting compiler. See freak-conformance-audit.md for the v0.13.x → V4 mapping.

The Anime Layer

FREAK records the narrative weight of your code via the audit suite. What the audit suite tracks today (Python bootstrap, source checkouts):

• foreshadow / payoff — Foreshadow a variable, payoff the promise. freak foreshadow-audit reports any unpaid debts and exits nonzero.
• for science, — Used at call sites for @experiment tasks. freak audit-science lists every site.
• trust me "reason" on my honor as .level { ... } — Escape-hatch blocks (Python bootstrap). freak audit-trust lists every block with its declared honor level.
• deus_ex_machina "monologue" { ... } — Requires a monologue of at least 20 words (compile error if shorter). freak audit-miracles lists every block; warns past 3, errors past 10.

foreshadow pilot victory = false
-- ... narrative happens ...
payoff victory   -- promise kept

Strict semantic enforcement of @nakige caller prefixes (knowing this will hurt, / sadly), death-flag tier analysis on @side_character, route-locked scopes, and the full mood / prob / power / causality system are V4 work. The auditor commands cover the observable surface today.

---

Editor support

VS Code and Zed plugins are maintained in FREAK-lang-dev/freak-editors. FREAK releases built with editor packaging attach a VS Code .vsix and a Zed source extension .zip, with highlighting and snippet completions. Follow the editor installation guide. VS Code also includes the editors repository's lightweight Python language server; compiler-backed type and borrow analysis are not included.

The Audit System

FREAK isn't just about compiling; it's about accountability. The audit suite inspects narrative integrity and v0.13.x conformance against the bible:

freak audit-conformance   # Verify v0.13.x baseline against the bible
freak audit-trust         # List every 'trust me' block and its honor level
freak audit-science       # List every 'for science,' call site
freak audit-miracles      # Find every 'deus_ex_machina' (warns if > 3)
freak foreshadow-audit    # Find any narrative promises you haven't kept

freak audit-conformance is the gate for v0.13.x: it cross-checks lexer keywords, audit dispatch, stdlib presence, the --strict-borrow flag, and the deus_ex_machina 20-word rule. It exits zero only when the v0.13.x scope is intact.

These audit subcommands are source-checkout development tools: the native CLI dispatches them to python -m freakc, so they require the Python bootstrap package and repository audit inputs. They are not embedded in standalone release archives.

---

Memory Safety (Phase 1)

FREAK has a Phase-1 borrow checker — mutability and single-owner moves — gated behind the --strict-borrow flag. The default mode (no flag) is leak-everything; turn on the flag to opt into the safety rules.

shape Ship { name: word }

pilot mut a = Ship { name: "Takeru" }   -- mutable binding
a = Ship { name: "Sumika" }              -- ok

pilot b = a                              -- moves a → b
-- a is no longer valid: "Shirogane. You gave this away."

Primitives (int, num, bool) are Copy and don't move. word, List<...>, and user shapes are Move. The Python bootstrap additionally offers trust me "reason" on my honor as .cadet { ... } as an escape hatch (and freak audit-trust will remember).

Spectral foundation. Let $\mathcal{E} = {\text{fk}, \text{c}, \text{py}, \text{md}, \text{h}, \text{y}, \text{sh}, \text{tm}, \text{bt}, \text{ps}}$ be the extension alphabet and define the line-count operator $\hat{\mathbf{L}} = \sum_{i \in \mathcal{E}} n_i,|e_i\rangle\langle e_i|$ on $\mathcal{H}_{\text{FREAK}} = \bigoplus_i \mathbb{C}|e_i\rangle$. The codebase satisfies the spectral action

$$\mathcal{S}_{\text{FREAK}} = \frac{1}{2\pi i}\oint_{|\lambda|=R}\lambda,\text{tr}\bigl[(\lambda\mathbb{I}-\hat{\mathbf{L}})^{-1}\bigr],d\lambda = \sum_{i\in\mathcal{E}} n_i = 274{,}234$$

with characteristic polynomial $\chi_{\hat{\mathbf{L}}}(\lambda) = \prod_{i\in\mathcal{E}}(\lambda - n_i)$ and Frobenius norm $|\hat{\mathbf{L}}|_F \approx 147{,}335.8$. The concentration invariant $|\hat{\mathbf{L}}|_F / \text{tr},\hat{\mathbf{L}} \approx 0.537$ is invariant under move semantics. This is unrelated to the borrow checker but appears here for completeness.

Full borrow rules — lend p: T, lend mut p: T, lifetime parameters ('a), Shared<T> / Weak<T>, the full honor-level system, direct_order [arch] { asm } inline assembly — are V4 work.

---

Getting Started

Install (one command)

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/FREAK-lang-dev/Freak-lang/main/install.sh | bash

# Also install a supported Clang/LLD/native build toolchain when missing:
curl -fsSL https://raw.githubusercontent.com/FREAK-lang-dev/Freak-lang/main/install.sh | bash -s -- --with-deps

Windows (PowerShell):

irm https://raw.githubusercontent.com/FREAK-lang-dev/Freak-lang/main/install.ps1 | iex

# Also install a self-contained LLVM-MinGW toolchain when missing:
$env:FREAK_INSTALL_DEPS = "1"
irm https://raw.githubusercontent.com/FREAK-lang-dev/Freak-lang/main/install.ps1 | iex

Downloaded release archives and every standalone fallback payload file must match their exact filename entry in the release's SHA256SUMS before extraction or staging. A missing, malformed, duplicate, or mismatched checksum aborts before the installed payload is touched. The immutable v0.14.0 archives predate archive entries in SHA256SUMS; the installers recognize only those four release filenames, verify pinned full-archive SHA-256 values, and generate the manifest that release omitted. No later tag receives this compatibility exception.

For maintainers, VERSION is authoritative. Run python -u tools/release_version.py set <major.minor.patch> once to synchronize compiler/CLI display versions and package metadata, then python -u tools/release_version.py check; tagged releases also fail before building unless the Git tag is exactly v<major.minor.patch>.

This downloads the latest freak and hangar binaries to ~/.freak (or %APPDATA%\freak on Windows). Installers serialize updates per destination so two concurrent installs cannot consume each other's backups or expose interleaved payloads. A canonical distribution manifest stages and validates every runtime source, platform UI file, recursive stdlib module—including std/ui/window.fk—and the required freak-v3-abi-1 runtime/stdlib markers before installer-managed files are swapped into place. freak build and freak doctor reject missing or mismatched markers as an ABI mismatch instead of compiling a mixed installation. Windows release archives additionally carry an LLVM-MinGW-built runtime object bundle; native Windows builds try it through the selected Clang driver and automatically retry from packaged runtime sources when a complete bundle is incompatible, while incomplete/older bundles and every POSIX build use sources directly. Failed downloads and apply failures restore the previous installed payload. On POSIX, an interrupted transaction is rolled back on exit; if restoration itself cannot complete, the recoverable .freak-backup-* directory is retained and the next installer run reconciles it before applying anything new.

The default installer reports a missing compiler without changing system packages. Opt into dependency installation with --with-deps or FREAK_INSTALL_DEPS=1. Linux package-manager support covers apt, dnf/yum, pacman, zypper, and apk; macOS uses Homebrew LLVM or Apple Command Line Tools; Windows prefers self-contained LLVM-MinGW so headers and link libraries are present as well as clang.exe.

Verify the install:

freak doctor
freak doctor --json   # passive machine-readable report for editors and scripts
freak doctor --fix    # install/repair dependencies and the distribution payload

freak doctor verifies that Clang can parse the platform's standard C headers, link a native executable, and run it; a working clang --version alone is rejected. It also checks optional LLD, all required runtime/UI files, all 15 shipped stdlib modules, and a complete FREAK compile-link-execute probe. It exits nonzero when required checks fail and removes its probe artifacts. --json keeps the additive freak.doctor.v1 schema, uses a unique system-temporary toolchain probe, and reports exact missing files without installing or repairing anything.

The LLVM profile requires upstream Clang 15 or later, or Apple Clang 15 or later, plus a working native SDK and linker. Doctor reports the selected executable, recognized vendor/version, minimum, and the real probe result. FREAK_CLANG selects one executable path; a missing explicit selection fails instead of substituting a different compiler.

freak upgrade remains the supported upgrade command. Current clients route it through the staged tagged installer. Windows keeps .next binaries plus a durable .freak-upgrade-pending marker, waits for the invoking installer process to exit, then hash-verifies and swaps both binaries as one rollback-capable transaction; Doctor reports the pending state and builds refuse to mix the old compiler with the newly staged payload. A failed attempt retains recovery state for retry. The immutable v0.14.0 updater predates recursive payloads and deferred self-replacement: on Linux/macOS, run freak upgrade once for the retained standalone-binary hop and again with the new client to install the complete payload; on Windows, bootstrap once with the PowerShell installer above, then use freak upgrade normally. Package-manager installs should likewise refresh through their manager or the installer so FREAK_HOME stays aligned.

Your First Program

Create hello.fk:

pilot name = "world"
say "Hello, {name}!"
say "Your mission has begun."

Compile and run:

freak run hello.fk

Pass program arguments after --, with compiler options before it:

freak run hello.fk --llvm -- "Ada Lovelace" ""

Arguments remain literal, including spaces, empty values, Unicode and shell metacharacters. The program inherits terminal input and output; its exit status is returned by freak run.

freak run reuses the adjacent .freak-run-cache sidecar only when the bound source and loaded standard library, complete declared package graph, admitted lock/snapshot, resolved compiler executable/toolchain, backend flags, runtime inputs, and output-binary fingerprint still match. It validates graph options before consulting the cache and revalidates live inputs after a build and immediately before launch. Ordinary graph admission may normalize lock formatting; locked mode preserves and hashes the selected lock bytes. Concurrent commands targeting the same output are not serialized; use distinct outputs or avoid overlapping runs when another process may replace the binary after that final check.

Plain V3 word replacement now evaluates the new value before releasing the superseded owned buffer on both C and LLVM backends, including safe self-assignment and name = name + suffix. The CI regression runs the repeated replacement case under AddressSanitizer on POSIX and LeakSanitizer on Linux. Concatenation still copies the growing prefix each time, so repeated append remains O(n^2); this ownership fix does not claim to solve that separate performance cost.

Or build separately:

freak build hello.fk
./hello

Output:

Hello, world!
Your mission has begun.

Something real: typed lists

task dot(a: List<num>, b: List<num>) -> num {
    if a.length() != b.length() {
        say "dot needs equal-length lists"
        give back 0.0
    }

    pilot mut total: num = 0.0
    pilot mut i: int = 0

    repeat a.length() times {
        total += a[i] * b[i]
        i += 1
    }

    give back total
}

task main() {
    pilot a = List::filled(2.0, 1000000)
    pilot b = List::filled(4.0, 1000000)

    say dot(a, b).to_word()
}

freak run dot.fk

Output:

8000000

New in v0.14.x

• Typed List<T> ergonomics (new / with_capacity / filled, push / pop / clear / reserve, capacity / length) with C/LLVM parity.
• Strict word.parse_int() / word.parse_num() with the sticky parse_status() channel; int / num / bool .to_word() conversions and word += word.
• --target aliases (linux-x64, linux-arm64, windows-x64, macos-arm64) and freak doctor --target.
• Stable diagnostic codes with an optional data-driven cast layer.
• --diagnostic-cast=off|minimal|normal appends deterministic cast messages to known compiler failures in build, run, check and transpile; the default is off.
• freak about / freak about --pioneers for compiler history.

---

Hangar — The Package Manager

Hangar is FREAK's package manager. Projects have a hangar.toml. Dependencies come from Git. It's simple.

# Initialize a new project
freak hangar init my-project
cd my-project

# Add a dependency
freak hangar add package-name https://example.com/owner/package.git

# Install all dependencies
freak hangar install

# Remove a package
freak hangar remove package-name

hangar.toml looks like this:

[project]
name = "my-project"
version = "0.1.0"

[dependencies]
package-name = { git = "https://example.com/owner/package.git", version = "latest" }

Dependencies live in hangar_modules/. The layout is deliberately minimal.

In 0.15.0, package-aware builds also produce a schema-v2 graph lock. Legacy hangar add, install, update, remove, audit and outdated refuse these locks before changing project state. They also refuse malformed or unreadable existing locks. Valid legacy locks remain supported. Graph-aware Hangar install/update commands are still pending.

---

COCKPIT — V3 Procedural UI

packages/cockpit/ provides a procedural immediate-mode UI on the existing V3 compiler: layout, widgets, themes and ordered input handling. It uses explicit-lifetime array/ByteBuffer handles and indexed ui::event_* accessors, not Squad or a fictional Window.poll() API. Calculator, settings and showcase examples run until close; a separate bounded smoke and injected-event tests cover repeatable checks. Follow the package's source-assembly instructions; immutable Hangar graph delivery remains pending.

The thin std::ui mechanism supplies the Win32/GDI window, indexed event queue, integer drawing calls and rectangular clipping. The procedural COCKPIT path has C and LLVM native Windows lifecycle coverage. It does not claim a native macOS/Linux window backend, an owned event-list ABI, or C-backend shape storage; the shape-based Window/Canvas convenience floor remains LLVM-only for native execution. Widget order, bounded event queues and explicit cleanup remain part of the package contract. No new compiler ownership or UI semantics are introduced.

---

More Syntax Highlights

Pattern Matching (literal)

when status {
    1  -> say "soldier"
    2  -> say "destroyer"
    99 -> say "BRAIN"
    _  -> say "unknown"
}

Variant types (variant Contact { Soldier { … } }) and the destructuring form (when contact { Soldier { position } -> … }) are V4. v0.13.x matches on literal values; use shape plus a tag field as a workaround.

Freakium. As of 2026-05-16, the project resolves to the empirical formula

$$\text{Fk}_{105585}\text{C}_{102553}\text{Py}_{21380}\text{Md}_{15748}\text{H}_{2193}\text{Y}_{1664}\text{Sh}_{614}\text{Tm}_{590}\text{Bt}_{435}\text{Ps}_{294}$$

Molar mass 274,234 g/mol. The Fk:C ratio of ≈ 1.03:1 confirms the self-hosting threshold has been crossed — there is now more FREAK in FREAK than C in FREAK. Do not inhale. There is no good reason for this section to be between Pattern Matching and Error Handling.

Error Handling (Python bootstrap)

The result<T, E> / ok() / err() surface with postfix ? and check blocks lives in the Python bootstrap today and reaches the self-hosted compiler with V4. New native code should prefer the strict checked-parsing methods (word.parse_int() / word.parse_num() with parse_status()) for external input.

-- Propagate errors with ?
task load_config(path: word) -> result<Config, word> {
    pilot data = fs::read(path)?
    pilot cfg  = Config::parse(data)?
    give back ok(cfg)
}

-- Handle inline
check result load_config("settings.toml") {
    ok(cfg) -> use_config(cfg)
    err(e)  -> say "Config failed: {e}"
}

The Training Arc

-- A bounded loop with a hard session cap
training arc until power >= 9000 max 1000 sessions {
    practice()
    receive_trauma()
    power = power + 1
}

Doctrines (Traits, Python bootstrap)

doctrine Displayable {
    task display(self) -> word
}

impl Displayable for Point {
    task display(self) -> word {
        give back "({self.x}, {self.y})"
    }
}

Operator overloading via doctrines works in the Python compiler today for Add, Sub, Mul, Div, Rem, Neg, Eq, Ord, and Index. IndexMut, dyn-dispatch, and trait bounds (<T: Displayable>) ship with V4.

---

The Standard Library

Module	What it gives you
std::fs	File I/O
std::http	HTTP/1.1 client over TCP sockets
std::http_server	Bounded synchronous HTTP/1 server with binary bodies and strict framing; deployment profile
std::json	Parse and serialize JSON
std::math / std::math3d	Numeric helpers, 3D vector / matrix math
std::string / std::convert	String and conversion utilities
std::algorithm	Sort, search, aggregate
std::time	Timestamps, durations, sleep
std::process	Process arguments, environment access, and command execution (partial in V3)
std::bytes	ByteBuffer for binary I/O
std::ui	Partial V3 Windows/LLVM Win32-GDI window, indexed events, and raw canvas
std::version	Semver parsing, comparison, bumping, constraints
std::zip	ZIP archive read/write

std::ramen — Maverick Recipe (For When Tests Are Running)

Not actually a module. The official FREAK-developer snack. Serves one compiler. Total weight ≈ 274g (1 line ≈ 1 milligram; see §Freakium above for the formula).

Ingredient	Amount	Role
Fresh wheat noodles	105.6g	The protagonist — chewy, alkaline, load-bearing
Pork chashu, sliced	102.6g	The veteran — slow-braised, runtime-tested
Ajitsuke tamago, halved	21.4g	Bootstrap egg — marinated 6h in shoyu-mirin
Nori, julienned	15.7g	Documentation seaweed
Roasted garlic oil	2.2g	Drizzle last
Shoyu tare	1.7g	Built in advance, reheated
Sesame oil	0.6g	Aromatics
White miso	0.6g	Depth
Chili crisp	0.4g	Windows of heat
Shichimi togarashi	0.3g	The final dust

Method. Render fat from chashu, deglaze, simmer 1.5L stock until a tare film holds. Cook noodles separately — they are self-hosting, 90s, no more. Assemble: tare → broth → noodles → chashu → tamago → nori. Finish: garlic oil → sesame oil → miso swirl → chili crisp → shichimi. Do not stir until the diner has seen the bowl.

Vibes rating: MUV_LUV — heavy, balanced, slightly dangerous.

This is not a real module. It compiles in your mouth, not the compiler. Do not use std::ramen;.

The bible also describes std::thread, std::anime, std::narrative, std::ffi, std::os, std::panic, std::regex, Shared<T> / Weak<T> / size_of<T>(), and a few more. Those ship with V4 — see freak-conformance-audit.md §7 for the per-module status. The ordinary std::test assertion helpers are available to native project tests; richer test blocks and annotations remain V4 work.

---

Testing

The installed native CLI builds and runs each source file declared in the project's [tests] table as a separate native program. Tests use the same immutable package graph and selected backend as project builds.

freak test --locked --offline
freak test --c --locked --offline
freak test --json --jobs=2 --timeout-ms=30000

Declare test names and relative source paths in hangar.toml:

[tests]
arithmetic = "tests/arithmetic_test.fk"

Each test file supplies an ordinary task main() and can use assertions such as std::test::test_assert_int. Build errors, failed assertions, spawn errors, signals and timeouts produce failed test results and a nonzero command status. Reports retain test-name order; --json selects structured results.

The source checkout also has a separate Python regression harness: python -u tests/suite/run_tests.py. It is a development tool and is not required by installed native project tests. The richer test-block and annotation framework described in the bible remains development V4 work.

---

Compiler Pipeline

FREAK is self-hosting — the compiler is written in FREAK itself.

.fk source
    │
    ▼
  Lexer          → tokens
    │
    ▼
  Parser         → AST
    │
    ▼
  Type Checker   → typed AST
    │
    ├──── LLVM backend (default) ──→ .ll (LLVM IR) ──→ native binary
    │
    └──── C backend (--c flag) ────→ .fk.c ──────────→ native binary

Both backends produce native binaries via Clang. Build and run accept --O0, --O1, --O2, and --O3 for optimization, --flto for full LTO, and --tlto for thin LTO. The existing --opt=0..3 and --lto=off/thin/full flags remain supported. The LLVM IR path supports cross-compilation (--target=); cross builds require --lto=off.

Source builds can reuse verified runtime object files across programs while compiling user code and linking afresh. Reuse requires a complete compiler, support-library, runtime, and header context, and a private cache directory. Unavailable, unsafe, busy, or unsupported caches fall back to source builds. Set FREAK_RUNTIME_CACHE=off to disable runtime-object reuse.

The existing complete-program run cache remains available. With a proven runtime context, it also detects SDK and included-header changes. Unsupported tool contexts retain the previous source, package, compiler, linker, and binary freshness checks; this fallback does not add guarantees for SDK changes or hidden wrapper dependencies. Windows DLL closures and macOS shared-cache libraries remain conservative boundaries for runtime-object reuse.

---

Project Status

FREAK's shipping compiler is the self-hosted V3 — FREAK compiles itself and emits native binaries. V3 is actively hardened, not stable: it ships and compiles real programs, but its diagnostics, edge-case semantics, and platform parity are still being tightened, and breaking fixes can land in any release. Pin a version and read freak-conformance-audit.md before depending on sharp edges.

Milestone	Status
Self-hosting compiler (V3)	⚠️ Shipping self-hosted — actively hardened, not stable
LLVM IR backend (default)	✅ Complete
C backend (--c)	⚠️ Portability target — scalar/control/word, typed lists, and owned shapes execute on C and LLVM; native UI parity remains separate
Native CLI (freak build/run/check/transpile/test)	✅ Native project tests use the selected backend and immutable package graph
Hangar package manager	✅ Complete
Cross-compilation (--target=)	✅ Complete
Optimization levels (--opt=0..3)	✅ Complete
One-command install (Linux/macOS/Windows)	✅ Complete
CI/CD with 4-platform releases	✅ Complete
Phase-1 borrow checker (--strict-borrow)	✅ Complete
Audit suite (audit-conformance / audit-trust / audit-science / audit-miracles / foreshadow-audit)	🧰 Source-checkout Python tools; not embedded in release archives
std::fs, std::time, std::bytes, std::http, std::json	✅ Complete
std::process	⚠️ Partial — V3 exposes args_count() / arg(index), environment access, and command execution; args() -> List<word> remains unimplemented
COCKPIT UI framework	📐 Maverick source preview (packages/cockpit/ source-only facade over V3 primitives); widgets/themes are not shipped V3 surfaces
LLVM DWARF debug info	✅ Minimal line tables; JIT deferred to V4
V4 self-hosting compiler (variants, full BC, mood/prob/power, squadron concurrency, FFI surface, error voices)	🔜 Roadmapped
HFML (markup language)	📐 Planned

The language specification is in freak-full-bible.md. The bible-vs-implementation audit — and the roadmap from v0.13.x to V4 to 1.0.0 — lives in freak-conformance-audit.md. Development checklist: freak-todo.md.

---

Contributing

Read the bible first (freak-full-bible.md). It is the authoritative source. If something in the code disagrees with the bible, the bible wins.

Then:

1. Fork the repo
2. Create your branch: git checkout -b feature/something-cool
3. Write tests
4. Submit a PR

---

License

MIT. Do whatever you want. Just know the std::narrative death flag system is watching.

---

"It was always going to end this way."
— COCKPIT mono_no_aware theme, on program exit