Section 11: Foreign Function Interface (FFI)

Goal: Enable Ori to call C libraries, system APIs, and JavaScript APIs (WASM target)

Criticality: CRITICAL — Without FFI, Ori cannot integrate with the software ecosystem

Proposal: proposals/approved/platform-ffi-proposal.md

Dependencies: Section 6 (Capabilities — uses FFI capability system must be in place)

Sync Points: CPtr and C ABI Types (multi-crate sync required)

Adding CPtr and C ABI types requires updates across these crates:

ori_ir — Add CPtr type variant, C type aliases (c_int, c_long, etc.)
ori_types — Register CPtr type, FFI-safety validation, Option<CPtr> nullability handling
ori_eval — CPtr runtime value representation, pointer operations in unsafe blocks
ori_llvm — CPtr maps to LLVM opaque ptr type, C calling convention codegen
library/std/ffi.ori — CPtr type definition, FfiError type (for Deep FFI)

Design Decisions (Approved)

Question	Decision	Rationale
Should FFI require capability?	Yes, `FFI` capability	Consistent with effect tracking
Single or multiple capabilities?	Single `FFI`	Platform-agnostic user code
Support C++ directly?	No	C ABI only; C++ via extern “C”
Support callbacks?	Yes (native)	Required for many C APIs
Memory management?	Manual in unsafe blocks	C doesn’t know about ARC
Async WASM handling?	Implicit JsPromise resolution	Preserves Ori’s “no await” philosophy
Unsafe operations?	`unsafe { ... }` blocks	Explicit marking for unverifiable ops

11.1 Extern Block Syntax

Spec section: spec/26-ffi.md § Extern Blocks

Native (C ABI)

extern "c" from "m" {
    @_sin (x: float) -> float as "sin"
    @_sqrt (x: float) -> float as "sqrt"
}

JavaScript (WASM)

extern "js" {
    @_sin (x: float) -> float as "Math.sin"
    @_now () -> float as "Date.now"
}

extern "js" from "./utils.js" {
    @_formatDate (timestamp: int) -> str as "formatDate"
}

Implementation

11.2 C ABI Types

Spec section: spec/26-ffi.md § C Types

Primitive Mappings

Ori Type	C Type	Size
`c_char`	`char`	1 byte
`c_short`	`short`	2 bytes
`c_int`	`int`	4 bytes
`c_long`	`long`	platform
`c_longlong`	`long long`	8 bytes
`c_float`	`float`	4 bytes
`c_double`	`double`	8 bytes
`c_size`	`size_t`	platform

CPtr Type

type CPtr  // Opaque pointer - cannot be dereferenced in Ori

extern "c" from "sqlite3" {
    @sqlite3_open (filename: str, db: CPtr) -> int
    @sqlite3_close (db: CPtr) -> int
}

// Nullable pointers
extern "c" from "foo" {
    @get_resource (id: int) -> Option<CPtr>
}

Implementation

11.3 #repr Attribute

Spec section: spec/26-ffi.md § C Structs Proposal: proposals/approved/repr-extensions-proposal.md

Syntax

Attribute	Effect
`#repr("c")`	C-compatible field layout and alignment
`#repr("packed")`	No padding between fields
`#repr("transparent")`	Same layout as single field
`#repr("aligned", N)`	Minimum N-byte alignment (N must be power of two)

#repr("c")
type CTimeSpec = { tv_sec: c_long, tv_nsec: c_long }

#repr("packed")
type PacketHeader = { version: byte, flags: byte, length: c_short }

#repr("transparent")
type FileHandle = { fd: c_int }

#repr("aligned", 64)
type CacheAligned = { value: int }

Combining: #repr("c") may combine with #repr("aligned", N). Other combinations are invalid.

Newtypes: Newtypes (type T = U) are implicitly transparent.

Implementation

11.4 Unsafe Expressions

Spec section: spec/26-ffi.md § Unsafe Expressions

Syntax

@raw_memory_access (ptr: CPtr, offset: int) -> byte uses FFI =
    // Direct pointer arithmetic - Ori cannot verify safety
    unsafe { ptr_read_byte(ptr: ptr, offset: offset) }

Semantics

Inside unsafe:

Dereference raw pointers
Pointer arithmetic
Access mutable statics
Transmute types

Implementation

11.5 FFI Capability

Spec section: spec/26-ffi.md § FFI Capability

Design

// FFI functions require FFI capability
@call_c_function () -> int uses FFI = some_c_function()

// Callers must have capability
@main () -> void uses FFI = {
    let result = call_c_function()
    print(msg: `Result: {result}`)
}

// Or provide it explicitly in tests
@test_c_call tests @call_c_function () -> void = {
    with FFI = AllowFFI in
        assert_eq(actual: call_c_function(), expected: 42)
}

Implementation

11.6 Callbacks (Native)

Spec section: spec/26-ffi.md § Callbacks

Syntax

extern "c" from "libc" {
    @qsort (
        base: [byte],
        nmemb: int,
        size: int,
        compar: (CPtr, CPtr) -> int
    ) -> void
}

@compare_ints (a: CPtr, b: CPtr) -> int uses FFI = ...
qsort(base: data, nmemb: len, size: 4, compar: compare_ints)

Implementation

11.7 Build System Integration

Spec section: spec/26-ffi.md § Linking

ori.toml Configuration

[native]
libraries = ["m", "z", "pthread"]
library_paths = ["/usr/local/lib", "./native/lib"]

[native.linux]
libraries = ["m", "rt"]

[native.macos]
libraries = ["m"]
frameworks = ["Security", "Foundation"]

[native.windows]
libraries = ["msvcrt"]

Implementation

11.8 compile_error Built-in

CROSS-REFERENCE: Section 13.10 also covers compile_error in the context of conditional compilation. Implementation should be done once and shared; avoid duplicate work.

Spec section: spec/annex-c-built-in-functions.md § Compile-Time Functions

Syntax

#target(arch: "wasm32")
compile_error("std.fs is not available for WASM.")

Implementation

11.9 WASM Target (Section 2)

JS FFI

extern "js" {
    @_sin (x: float) -> float as "Math.sin"
    @_fetch (url: str) -> JsPromise<JsValue> as "fetch"
}

Implementation

11.10 JsValue and Async (Section 3-4)

JsValue Type

type JsValue = { _handle: int }

extern "js" {
    @_document_query (selector: str) -> JsValue
    @_drop_js_value (handle: JsValue) -> void
}

JsPromise with Implicit Resolution

extern "js" {
    @_fetch (url: str) -> JsPromise<JsValue> as "fetch"
}

// JsPromise auto-resolved at binding sites
@fetch_text (url: str) -> str uses Async, FFI =
    {
        let response = _fetch(url: url),  // auto-resolved
        text
    }

Implementation

11.11 Deep FFI — Higher-Level FFI Abstractions

Proposal: proposals/approved/deep-ffi-proposal.md

Deep FFI layers five opt-in abstractions on top of the base FFI syntax: error protocols, ownership annotations, declarative marshalling, capability-gated testability, and const-generic safety. Each is independently useful and backward-compatible.

11.11.1 Error Protocols + `out` Parameters (Phase 1)

11.11.2 Ownership Annotations (Phase 2)

11.11.3 Declarative Marshalling Extensions (Phase 3)

11.11.4 Capability-Gated Testability (Phase 4)

11.11.5 Const-Generic Safety (Phase 5 — Future)

Design: Where clauses on extern items with const expressions
- Depends on Section 18 (Const Generics) being complete
Implement: Buffer size validation at compile time
Implement: Fixed-capacity list [T, max N] at FFI boundary

Section Completion Checklist

Exit Criteria: Can write a program that opens and queries a SQLite database

Example: SQLite Binding

Target capability demonstration:

extern "c" from "sqlite3" {
    @_sqlite3_open (filename: str, ppDb: CPtr) -> int as "sqlite3_open"
    @_sqlite3_close (db: CPtr) -> int as "sqlite3_close"
    @_sqlite3_exec (
        db: CPtr,
        sql: str,
        callback: (CPtr, int, CPtr, CPtr) -> int,
        userdata: CPtr,
        errmsg: CPtr
    ) -> int as "sqlite3_exec"
}

type SqliteDb = { handle: CPtr }

impl SqliteDb {
    pub @open (path: str) -> Result<SqliteDb, str> uses FFI =
        {
            let handle = CPtr.null()
            let result = _sqlite3_open(filename: path, ppDb: handle)
            if result == 0 then
                Ok(SqliteDb { handle: handle })
            else
                Err("Failed to open database")
        }

    pub @close (self) -> void uses FFI =
        _sqlite3_close(db: self.handle)
}

Section 11: Foreign Function Interface (FFI)

Sync Points: CPtr and C ABI Types (multi-crate sync required)

Design Decisions (Approved)

11.1 Extern Block Syntax

Native (C ABI)

JavaScript (WASM)

Implementation

11.2 C ABI Types

Primitive Mappings

CPtr Type

Implementation

11.3 #repr Attribute

Syntax

Implementation

11.4 Unsafe Expressions

Syntax

Semantics

Implementation

11.5 FFI Capability

Design

Implementation

11.6 Callbacks (Native)

Syntax

Implementation

11.7 Build System Integration

ori.toml Configuration

Implementation

11.8 compile_error Built-in

Syntax

Implementation

11.9 WASM Target (Section 2)

JS FFI

Implementation

11.10 JsValue and Async (Section 3-4)

JsValue Type

JsPromise with Implicit Resolution

Implementation

11.11 Deep FFI — Higher-Level FFI Abstractions

11.11.1 Error Protocols + out Parameters (Phase 1)

11.11.2 Ownership Annotations (Phase 2)

11.11.3 Declarative Marshalling Extensions (Phase 3)

11.11.4 Capability-Gated Testability (Phase 4)

11.11.5 Const-Generic Safety (Phase 5 — Future)

Section Completion Checklist

Example: SQLite Binding

11.11.1 Error Protocols + `out` Parameters (Phase 1)