Architecture & Analysis

This document provides a comprehensive architectural analysis of Flame’s compilation pipeline, specialized native runtime construction, dependency analysis, package interface layer (.fmi), and execution model.

---

Core Architectural Principles

Every Flame application receives a specialized native runtime containing only the runtime capabilities, packages, and native implementations actually required by that application.

Flame analyzes the application’s imports and dependencies, resolves the required package .fmi interfaces, and constructs the appropriate runtime. The resulting runtime is built as native code through Rust, Cargo, and LLVM, allowing Flame to maintain a small, dependency-specific runtime and an optimized native binary.

Normal builds use the real filesystem. VFS is used only when the developer explicitly requests a self-contained single executable.

What 'Runtime' Means in Flame

Flame does not use a traditional bytecode VM or universal interpreter. “Runtime” refers to the native runtime components required by the application, which are compiled into the final native binary.

What Flame Is vs. What Flame Isn’t

Before diving into the compiler architecture, it is helpful to establish clear technical boundaries:

What Flame Is	What Flame Isn’t
A simpler, type-safe language built to work alongside Rust	Not a Rust replacement (not meant for kernel-level or micro-optimized low-level systems)
A tool for high developer velocity, application logic, and scripting	Not a source-to-source Rust transpiler
Specialized native runtime via Blaze dependency analysis	Not a universal bytecode VM or monolithic interpreter (like Node.js, Python, or the JVM)
Deterministic memory safety via ownership, borrows, and references	Not a garbage-collected language (no GC pauses or runtime sweeps)
Smart ABI plugin system (.fmi) for direct Rust interop	Not claiming unqualified “zero-cost” interop without context
Leverages Rust, Cargo, and LLVM for native code generation	Not claiming to magically outperform hand-written Rust
Super embeddable into existing Rust codebases via flamebinder	Not an isolated language silo

---

1. Application-Specific Runtime

Flame is a compiled language with application-specific native runtimes. Rather than requiring a large, universal runtime that contains every language feature, standard library module, and package, Flame generates and configures a tailored native runtime for each individual application.

Flame was built around a practical reality: maintaining a massive, monolithic Rust codebase can be difficult and slow down iteration. Writing high-level business logic, glue code, dynamic configurations, or scripting in low-level Rust often leads to borrow-checker friction and lengthy compilation cycles for simple tasks. Flame allows teams to write core systems and performance primitives in Rust, and use Flame for simpler application layers, glue code, and rapid scripting.

The central compilation and runtime architecture operates as follows:

             Flame source
                  ↓
                Blaze
                  ↓
          Dependency analysis
                  ↓
     ┌─────────────────────────┐
     │ Application-specific    │
     │ native runtime          │
     │                         │
     │ only required pieces    │
     └─────────────────────────┘
                  ↓
             Rust / Cargo
                  ↓
                LLVM
                  ↓
            Native binary

Flame analyzes the application’s dependency graph, constructs a runtime containing the required native components, and builds that runtime into the application’s native binary through Rust/Cargo/LLVM.

Dependency-Aware Runtime Construction

The runtime is configured specifically for the application’s actual requirements. It includes only the Flame runtime capabilities, runtime components, packages, and native implementations that the application actually imports and uses.

For example, consider an application with the following imports:

import std.net.http
import std.json
import flamer
import bot

During compilation, Blaze performs dependency analysis:

• It includes the HTTP runtime support (std.net.http), JSON parsing routines (std.json), and the native implementations required by flamer and bot.
• It does not include unused standard library modules (such as std.bluetooth, std.camera, std.desktop, or std.serial).
• It does not include unrelated native plugins or unreferenced runtime subsystems.

This dependency-aware runtime construction ensures that your production binaries remain lean, purpose-built, and free of extraneous bloat.

---

2. Minimal and Optimized Runtime

Flame performs runtime specialization based on the application’s dependency graph:

Application
     │
     ├── imports A
     ├── imports B
     └── imports C
             ↓
      Dependency Analysis
             ↓
       Required Runtime
       ├── Core runtime
       ├── A
       ├── B
       ├── C
       └── required native implementations

Unused packages, standard library modules, and unused native runtime components are strictly excluded from the application’s runtime.

Key Architectural Benefits

• Smaller Runtime Footprint: The application embeds only what it needs, avoiding the memory overhead of monolithic runtimes.
• Smaller Production Binaries: Dead code and unreferenced native crates are eliminated before linking.
• Reduced Unnecessary Code: Minimized attack surface and cleaner execution profiles.
• Less Runtime Initialization: Startup routines only initialize components required by the active dependencies.
• Better Deployment Efficiency: Lean containers and minimal container images deploy faster across edge nodes and cloud clusters.
• Improved Optimization Opportunities: The LLVM backend can perform aggressive link-time optimization (LTO) across the specialized runtime code.
• Native Execution Without Universal Runtimes: Every app gets native execution without requiring a massive multi-gigabyte universal interpreter.

Not a Universal Runtime

Flame avoids the traditional paradigm of shipping a large, one-size-fits-all runtime engine (like Python, Node.js, or the JVM) that includes every possible package. Each Flame binary carries only its own specialized runtime.

---

3. Native Performance

The application-specific runtime is itself native machine code, built through the standard Rust / Cargo / LLVM toolchain:

Flame
  ↓
Blaze
  ↓
Specialized Runtime
  ↓
Rust / Cargo
  ↓
LLVM
  ↓
Native Machine Code

Flame does not rely on a universal bytecode interpreter or VM for application execution. The required runtime components are compiled into the native application. Instead:

• The runtime is native and specialized specifically for the application’s requirements.
• The native Rust/Cargo/LLVM toolchain applies compiler optimizations: dead-code elimination, inlining, and Link-Time Optimization (lto = "fat").
• By avoiding unnecessary runtime components, Flame keeps binaries lean, avoids universal VM initialization delays, and statically links native Rust plugins and Smart ABI bindings at compile time.

Performance Reality

This architecture does not make Flame magically faster than every other language, but it guarantees that Flame avoids the bloat, initialization lag, and memory overhead of generic runtimes while letting LLVM generate optimal native machine instructions.

---

4. Smart ABI Plugin System & Native Rust Interop

Native Rust plugins and crates are first-class citizens in Flame’s runtime architecture. Flame uses a Smart ABI plugin system powered by .fmi (Flame Module Interface) metadata to bridge Flame and Rust.

Flame was specifically designed to work alongside Rust, not replace it:

• Maintaining a large codebase purely in Rust can become cumbersome when managing frequent changes to high-level application flows, web routing, or scripting hooks.
• With Flame, you keep your high-performance engines, low-level data structures, and hardware interfaces in Rust crates or plugins, and wire them together using Flame’s simpler, type-safe syntax.
• The Smart ABI system allows Flame code to call native Rust functions, construct structs, and pass data across the plugin boundary using declared .fmi interface contracts.

Native Rust implementations are incorporated only when required by the application’s dependency graph:

Application
   │
   ├── Flame source
   ├── flame.toml
   └── package .fm + .fmi
            ↓
      Dependency Analysis
            ↓
   Required native plugins
            ↓
   Application Runtime
            ↓
      Cargo + LLVM
            ↓
       Native Binary

If a native plugin is not imported or required by the code paths, it is completely excluded from the application’s runtime.

---

5. Package Management

Flame applications declare their dependencies cleanly in flame.toml:

[dependencies]
flamer = "0.2.0"
bot = "1.0.0"
news = "0.1.5"

The developer only maintains the Flame application source code and its dependency declarations in flame.toml.

To resolve and install packages, run:

fmp install

The package manager resolves the packages from their configured GitHub repositories or package registries:

flame.toml
     ↓
flame install
     ↓
GitHub / Package Source
     ↓
Flame Package
   ├── .fm  (Flame Source)
   └── .fmi (Interface Metadata)

The application developer never needs to manually copy Rust plugin source code, Cargo projects, DLL project directories, or native implementation trees into the application. Native implementations are seamlessly handled by Flame’s runtime creation and build infrastructure.

---

6. .fmi Interface Metadata

The .fmi format serves as Flame’s native package interface and metadata layer.

.fmi allows Flame and Blaze to understand the exact API exposed by a native package without requiring the application to contain the underlying native Rust implementation source:

Rust Native Implementation
          ↓
         .fmi
          ↓
   Flame Package Interface
          ↓
     Flame Application

What .fmi Describes:

• Functions & Methods: Exported function signatures, method receivers, and constructors.
• Structs & Types: Field layouts, visibility, and data types.
• Parameters & Return Types: Type signatures across the FFI boundary.
• Async Behavior: Whether functions return asynchronous futures or require persistent event loops (#[flame(daemon)]).
• Constructors & Receivers: Static constructors vs instance methods.
• Runtime Requirements & Permissions: System permissions (network, filesystem) and required runtime capabilities.
• Documentation: Rich documentation comments displayed in IDE hovers.

The application source depends only on the Flame-side package source (.fm) and the .fmi interface metadata. During build time, the native Rust implementation is resolved into the application-specific runtime.

---

7. Normal fmp build

Running fmp build is the standard build mode for Flame applications:

fmp build

Normal builds operate on the normal filesystem. They do not use VFS (Virtual File System).

The standard build pipeline is:

Flame source
     ↓
Read flame.toml
     ↓
Resolve installed packages
     ↓
Analyze imports and usage
     ↓
Resolve required .fmi metadata
     ↓
Select only required runtime/native components
     ↓
Create application-specific runtime
     ↓
Build through Rust / Cargo / LLVM
     ↓
Native application (target/dev/)

The output is an unoptimized development executable that reads from and writes to the real filesystem.

---

8. Normal fmp build --release

For production deployment, run:

fmp build --release

This command executes the same application-specific runtime architecture, with full LLVM release optimizations enabled:

fmp build

Application
    ↓
Specialized Runtime
    ↓
Native Binary
    ↓
Normal Filesystem Deployment

and:

fmp build --release

Application
    ↓
Specialized + Optimized Runtime
    ↓
Rust / Cargo / LLVM Optimization
    ↓
Optimized Native Binary (target/release/)
    ↓
Normal Filesystem Deployment

fmp build --release still does not use VFS. It benefits from:

• Full compiler optimization (opt-level = 3, lto = "fat", codegen-units = 1).
• Stripped debug symbols (strip = true).
• Elimination of all unused packages and unreferenced runtime components.
• Normal, direct filesystem access.

---

9. Single Executable Mode (--exe / --vfs)

Virtual File System (VFS) is used only when the developer explicitly requests a self-contained single executable:

# Debug single executable
fmp build --vfs

# Optimized production single executable
fmp build --vfs --release

In this mode, the architecture embeds application files and package scripts directly into the binary:

Flame Source
     ↓
Dependency Analysis
     ↓
Application-Specific Runtime
     ↓
Native Build
     ↓
Embed application files / resources
     ↓
VFS
     ↓
Single Executable

The VFS is an optional packaging mechanism, not the normal Flame runtime.

---

10. VFS Is Not the Runtime Architecture

It is critical to distinguish between Flame’s execution runtime and its optional packaging mechanism:

Normal Flame:
Application ──► Application-Specific Runtime ──► Real Filesystem

Single Executable:
Application ──► Application-Specific Runtime ──► Embedded VFS ──► Single Executable

• Normal Flame applications execute directly against the real host filesystem.
• VFS exists solely to make single-file executables self-contained when explicitly requested.
• Normal flame build and flame build --release do not use VFS.

---

11. Source Code Distribution

A Flame application source repository contains only Flame-level code and configuration:

my_app/
├── flame.toml
└── src/
    ├── main.fm
    └── ...

Installed packages provide their Flame-side source (.fm) and .fmi metadata inside .flame/pkg/.

The application repository does not contain:

• Rust source code.
• Cargo projects for each package.
• Rust plugin implementation trees.
• Native plugin source code or C/C++ compilation scripts.

Developers simply run:

fmp install
fmp build --release

The runtime creation system automatically generates the application-specific native runtime.

---

12. Production Deployment Summary

Deployment Mode	Command	Runtime	Filesystem	Best Used For
Normal Production	flame build --release	Specialized Native Runtime	Real Filesystem	Web servers, microservices, container images (Docker), cloud VMs
Self-Contained Single EXE	flame build --vfs --release	Specialized Native Runtime	Embedded VFS	Standalone CLI tools, desktop utilities, single-binary distribution

Developers never need to manually write Cargo files, copy Rust plugin source, or assemble native bindings.

---

13. Important Terminology

To maintain clarity across documentation, community discussions, and tools, Flame uses the following canonical terminology:

Prefer	Avoid / Inaccurate	Why
Application-Specific Runtime	Universal runtime / Monolithic VM	Flame constructs a specialized native runtime with only the modules and plugins your app imports; it does not ship a large, generic interpreter engine.
Specialized Native Runtime	Rust source-to-source transpiler	Blaze analyzes dependencies and orchestrates the native build pipeline via Cargo/LLVM rather than simply emitting raw .rs files for the user to compile.
Smart ABI Interface Metadata (.fmi)	Raw Rust source dependency	Application developers consume typed .fmi contracts and interface definitions without having to manually copy or manage Rust crate trees.
Native Execution via LLVM	Pure bytecode VM	Application execution occurs through native binaries compiled by Cargo and LLVM, rather than a generic bytecode VM interpreter loop.
Normal Build (Real Filesystem)	VFS-based runtime	Normal builds (fmp build / fmp build --release) interact directly with the real host filesystem.
Single Executable (Embedded VFS)	Normal build with VFS	VFS is an optional packaging mechanism used only when --exe or --vfs is explicitly requested.

The Central Architectural Distinction

                    FLAME
                      │
                      ▼
                    Blaze
                      │
                      ▼
             Dependency Analysis
                      │
                      ▼
        Application-Specific Runtime
             │                  │
             │                  │
       Normal Build       Single EXE
             │                  │
             ▼                  ▼
      Real Filesystem          VFS
             │                  │
             └────────┬─────────┘
                      ▼
               Native Binary
                      │
                 Rust/Cargo
                      │
                    LLVM

---

14. Compile-Time Memory Management

Flame manages memory using a deterministic Ownership and Borrowing model without a garbage collector.

Zero Garbage Collection

Flame does not have a garbage collector (GC). There are no stop-the-world pauses, runtime sweeps, or latency spikes. Memory is reclaimed deterministically via RAII as variables go out of scope.

1. Single Ownership: Each allocated value has a single owning binding. When the owner exits its lexical scope, its resources are dropped immediately.
2. Borrow Checking: Values can be borrowed immutably (&T) or mutably (&mut T). Concurrency boundaries enforce snapshot isolation (Arc<Env>), preventing pointer invalidation across execution contexts.
3. Data-Race Free Concurrency: Concurrency boundaries enforce isolated execution contexts, preventing shared mutable data races across thread boundaries.

---

15. Smart Runtime Reuse & Rapid Rebuild System (fmp run & fmp run --watch)

One of the historical trade-offs in systems programming languages is the tension between native compilation performance and rapid development iteration speed. Compiling through Cargo and LLVM on every single line edit introduces multi-second compilation and linking pauses that disrupt developer flow. Conversely, dynamic interpreted languages offer fast reloads but sacrifice raw execution throughput and typed native safety.

Flame eliminates this trade-off through an intelligent Host Runtime Reuse and Dependency-Driven Rebuild Architecture.

               fmp run / fmp run --watch
                         │
                         ▼
             Has dependencies or imports changed?
               (Exact Cargo feature set & mtimes)
                         │
           ┌─────────────┴─────────────┐
           │ YES                       │ NO
           ▼                           ▼
   Targeted Host Rebuild       Reuse Cached Dev Binary
(Compile tailored features     (Direct execution with
 to target/dev/<pkg_name>)     FLAME_ENTRY_FILE in <5ms)
           │                           │
           └─────────────┬─────────────┘
                         ▼
             Run Application Instantaneously

1. Reusable Host Dev Binary (target/dev/<pkg_name>)

When you run fmp run for the first time in a project, Blaze analyzes your dependencies and compiles a tailored development host runtime into target/dev/<pkg_name> (e.g. target/dev/my_app.exe on Windows or target/dev/my_app on Linux/macOS).

This binary embeds the exact native plugins, C/Rust crates, and standard library modules required by your project. Crucially:

• Subsequent fmp run calls bypass Cargo and LLVM: When executing fmp run src/main.fm, Flame detects that the host binary is already up to date. It launches the cached dev binary directly, passing FLAME_ENTRY_FILE.
• Zero Linking Delay: Pure code modifications—such as tweaking business logic, writing functions, adjusting formulas, or altering control flow—execute instantaneously in sub-milliseconds because the host binary already contains the execution engine and compiled native libraries.

2. Exact Feature-Set Matching on Import Changes

A common failure mode in naive caching systems is running stale dependencies or failing to link newly imported native modules. Flame prevents this using exact feature set reconciliation:

1. Required Features Scan: During every run, Flame scans src/ (and @Application(features = [...]) declarations) to compute the exact set of required Cargo features (e.g. ["http", "net", "thread", "fs"]).
2. Compiled Features Inspection: Flame reads the active dependencies recorded in .flame/build-cache/Cargo.toml to extract compiled_features.
3. Rebuild Trigger Condition:
   • Import Added: If you add import std.net.http, Flame detects that http is missing from compiled_features. It automatically invalidates the cached binary and rebuilds the host runtime with HTTP support linked.
   • Import Removed: If you delete an unused module import, Flame detects the reduced feature set and updates the runtime cleanly.
   • Manifest / Native Edits: File modification timestamps across flame.toml, native/, and .flame/pkg/ are continuously tracked. Editing a Rust plugin in native/src/lib.rs or adding a crate to [native-dependencies] immediately triggers a rebuild.

3. Development Speed in Watch Mode (fmp run --watch / -w)

For maximum productivity, Flame provides a built-in file watcher:

# Watch mode with instant reloading
fmp run --watch

# Shorthand alias
fmp run -w

Watch mode maintains an active event loop over your project directory:

• Instant Hot Rerun (< 5ms): Whenever you save an edit to any .fm file that does not alter dependencies or imports, the watcher executes the existing host runtime immediately. You experience the responsiveness of an interpreted scripting environment combined with the type safety and memory model of a compiled language.
• Seamless Background Rebuilds: If you add an import (such as import std.thread), register a native plugin, or edit flame.toml, watch mode detects the dependency change, recompiles the host runtime in the background, and resumes watching without requiring you to restart the terminal process.

---

16. Performance Highlights

Application-Specific

Each application gets a specialized native runtime containing only the modules, features, and plugins it actually imports.

Zero GC Pauses

Memory is reclaimed deterministically as variables exit scope, ensuring real-time responsiveness and predictable latency.

Instant Startup

Specialized native binaries execute without cold-boot overhead or universal VM initialization steps.

LLVM Optimizations

Leverages Rust Cargo and LLVM pipelines with fat LTO, symbol stripping, and single-unit codegen for maximum throughput.