Section 53: Foreign Function Interfaces and Interoperability¶

TECHSPEC-53 — Section 53 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Purpose¶

Foreign Function Interfaces (FFIs) allow programs written in this language to call external libraries and allow other languages to call its functions.

FFIs cross language and runtime boundaries, so they require explicit contracts and safety controls.

2. Foreign Declarations¶

A foreign function declaration must specify: - External symbol and library identity. - Calling convention. - Parameter and return representation. - Ownership and lifetime behavior. - Effects and permissions. - Failure behavior. - Thread-safety and reentrancy properties where known. - ABI and platform requirements.

3. Type Mapping¶

Mappings between language types and foreign types must be explicit.

The compiler must reject unsupported or ambiguous mappings. It must not assume that similarly named types have identical representation or semantics.

4. Memory and Ownership¶

The FFI contract must specify: - Which side allocates memory. - Which side releases memory. - Whether values are copied or borrowed. - Whether pointers may be retained. - Whether callbacks can occur later. - Whether data may be mutated externally.

The language's ownership rules must not be bypassed by an undocumented foreign pointer.

5. Error Mapping¶

Foreign errors, exceptions, status codes, and process faults must be mapped into explicit language-level outcomes where possible.

The mapping must preserve relevant error information and must not silently convert failure into success.

6. Unsafe Boundaries¶

Operations that cannot be verified by the compiler must be marked as unsafe or otherwise explicitly unverified.

Unsafe code must have a documented boundary, stated assumptions, and a reviewable interface.

7. Callbacks and Concurrency¶

Callbacks must define: - Calling thread or execution context. - Lifetime. - Reentrancy rules. - Cancellation behavior. - Error propagation. - Ownership of callback data.

8. ABI Compatibility¶

Binary compatibility depends on platform, compiler, architecture, calling convention, and library version.

The build must record relevant ABI assumptions. Compatibility must not be inferred from source-level signature similarity alone.

9. Verification¶

Reports distinguish language-checked properties, foreign declarations, externally supplied guarantees, runtime checks, and unverified assumptions.

10. MVP Scope¶

FFI support is deferred until the language's type, memory, ownership, and effect models are stable.

11. Design Goal¶

Interoperability must be explicit about the boundary it crosses and the guarantees that stop at that boundary.

Source file: TECHSPEC-53.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.