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), Section 18 (Const Generics — Deep FFI Phase 5)

Verification summary (2026-03-29): ~30% infrastructure exists (parser/IR/formatter/typeck), concentrated in 11.1, 11.3, and 11.4. Zero end-to-end FFI capability — no Ori program can call a C function today. The heavy lifting (codegen, linking, CPtr type system, capability enforcement) remains. Grammar (grammar.ebnf) and spec (spec/26-ffi.md, 554 lines) are comprehensive.

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

NOTE: Zero end-to-end FFI capability — no Ori program can actually call a C function today. Parser infrastructure is complete but codegen gap means extern blocks are parsed and stored but never processed into callable functions.

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (11.1) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-11.1 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 11.1: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

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

NOTE: E2041 compile-fail tests serve as semantic pins — they would break if repr validation logic is removed. Good positive + negative pairing (3 positive, 14 negative).

HYGIENE: ori_parse/src/grammar/attr/repr.rs line 5 contains stale plan annotation (TPR-01-043) — should be cleaned up per CLAUDE.md plan annotation rules.

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (11.3) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-11.3 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 11.3: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

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

WEAK TESTS: Current tests only verify unsafe { expr } preserves expression type. No tests for capability enforcement (uses Unsafe), no tests for operations that should require unsafe context, no interaction tests. Tests are correct for what they verify but incomplete for safety enforcement.

Test: tests/compile-fail/ffi/unsafe_required.ori
- Pointer deref outside unsafe
- Unsafe op without unsafe block
/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (11.4) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-11.4 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 11.4: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

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
/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (11.11) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-11.11 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 11.11: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

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)
}

11.12 Post-FFI Sanitizer Tooling Upgrade

Depends on: 11.1-11.7 (working extern "c" from "lib" in AOT compilation)

Context: Section 08 of plans/llvm-verification-tooling implemented sanitizer integration (ASan/UBSan via Clang delegation) with a smoke test suite of 17 Ori programs. The suite includes a semantic pin — a test that deliberately triggers a heap-use-after-free to prove ASan detects real memory errors. However, the semantic pin currently uses a C-only workaround (tests/sanitizer/pin_helper.c compiled directly by scripts/sanitizer-smoke.sh) because Ori’s extern "c" from "lib" blocks don’t resolve in AOT compilation — the type checker rejects the extern function identifier before linking has a chance to find the library.

Once FFI is fully implemented (extern blocks resolve in AOT, CPtr operations work, from "lib" links local libraries), the sanitizer tooling should be upgraded to use Ori-native FFI instead of the C workaround.

Why this matters: The C-only semantic pin proves ASan works on the CI host but does NOT prove that Ori’s sanitizer pipeline (env var → SanitizerMode → Clang delegation → linker -fsanitize flags → ASan-instrumented ori_rt) correctly instruments Ori FFI calls. A Clang-compiled C program with ASan is a baseline that any CI host can pass. The real test — an Ori program that calls a C function through the full compilation pipeline and has ASan catch a UAF in the C code — requires working FFI.

Checklist

Restore Ori-native semantic pin — rewrite tests/sanitizer/semantic_pin_asan.ori to use extern "c" from "pin_helper" with the existing pin_helper.c:
```
extern "c" from "pin_helper" {
    @_trigger_use_after_free () -> int as "trigger_use_after_free"
}

@main () -> int = {
    _trigger_use_after_free()
}
```
This program should compile via ori build with ORI_SANITIZE=address, link libpin_helper.a, and have ASan catch the UAF in the C code.
Update scripts/sanitizer-smoke.sh — the smoke script currently compiles pin_helper.c into a static library and runs it as a standalone C program. Once the Ori semantic pin compiles, change the script to:
1. Build libpin_helper.a from pin_helper.c (same as now)
2. Compile the Ori semantic pin via $ORI build --release tests/sanitizer/semantic_pin_asan.ori -o $TMPDIR/san_semantic_pin -L $PIN_LIB
3. Run the resulting binary and verify ASan catches the UAF This validates the full pipeline: Ori source → type checker (resolves extern) → LLVM codegen → Clang delegation (adds sanitizer passes) → linker (links libpin_helper.a + ASan runtime) → binary with ASan active.
Add FFI-specific smoke tests — once extern blocks work in AOT, add these to tests/sanitizer/:
- ffi_alloc_free.ori — call malloc/free via FFI, verify no leaks with ASan
- ffi_string_pass.ori — pass Ori str to a C function via CPtr, verify no buffer overflow
- ffi_callback.ori — pass an Ori closure as a C callback, verify the callback’s captures are correctly RC’d under ASan These exercise the FFI ↔ ARC interaction surface — the most likely source of sanitizer-detectable bugs.
Remove C-only workaround — once the Ori-native semantic pin is verified working in CI:
1. Delete the C-only compilation path from sanitizer-smoke.sh
2. Update pin_helper.c comment to note it’s linked via Ori FFI, not compiled standalone
3. Update Section 08’s TPR block to note the upgrade
Update nightly-verification.yml — if any new smoke tests require library compilation, add the build step to the CI workflow.
Verify end-to-end — the upgraded semantic pin must:
- Exit cleanly (0) when compiled WITHOUT ORI_SANITIZE
- Exit with ASan error (heap-use-after-free report on stderr) when compiled WITH ORI_SANITIZE=address
- Complete within the 60-second smoke budget

Bug Reference

This subsection exists because of BUG-04-074 (empty list literal unresolved type variables in AOT — tangentially related) and the broader issue that extern "c" from "lib" blocks don’t resolve in AOT mode. The latter is not yet filed as a standalone bug because it’s inherent to FFI being incomplete (Section 11.1 notes “typeck+codegen missing”). Once 11.1-11.7 are complete, the extern block resolution is a natural side-effect — no separate bug fix needed.

Cross-References

plans/llvm-verification-tooling/section-08-sanitizers.md — Section 08 implementation and TPR findings
tests/sanitizer/pin_helper.c — the C helper with the deliberate heap-use-after-free
scripts/sanitizer-smoke.sh — the smoke runner that handles the semantic pin

Verification Notes (2026-03-29)

Verified by: Claude Opus 4.6 (1M context)
Estimated completion at time of verification: ~30% infrastructure, ~0% end-to-end functionality
11.1 parser/IR/formatter COMPLETE (20 Rust tests), typeck/codegen NEEDS IMPLEMENTATION
11.3 parser/IR/typeck COMPLETE (17+ spec tests incl 14 compile-fail), codegen NEEDS IMPLEMENTATION
11.4 parser/typeck/eval/ARC COMPLETE (6 spec tests), WEAK TESTS on capability enforcement
Zero E2E FFI capability — no Ori program can call a C function today
Stale plan annotation TPR-01-043 in ori_parse/src/grammar/attr/repr.rs:5
scripts/build-rt-asan.sh — builds the ASan-instrumented ori_rt

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.12 Post-FFI Sanitizer Tooling Upgrade

Checklist

Bug Reference

Cross-References

Verification Notes (2026-03-29)

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