<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
The **C ABI profile** is the normative mapping from **[Interop.Contracts](/platform-spec/language-meta/interop/interop-contracts/)** primitives to **C-compatible** foreign libraries on tier-1 hosts. v0.3 **Standard** conformance uses **link-time** binding ([link-time linking](/platform-spec/language-meta/interop/c-abi-profile/link-time-linking/)), **interop view types** ([interop view types](/platform-spec/language-meta/interop/c-abi-profile/interop-view-types/)), and **System V AMD64** for the reference compiler path.

**Dynamic resolution** (`dlopen` / `dlsym`) is a **Proposed** appendix only ([dynamic resolution profile](/platform-spec/language-meta/interop/c-abi-profile/dynamic-resolution-profile/)). **WinAPI** is **out of scope** for stdlib Standard ([platform tier matrix](/platform-spec/language-meta/interop/c-abi-profile/platform-tier-matrix/)).

Lowering uses **Cranelift**; foreign libraries need only expose C ABI entrypoints compatible with emitted calls.
</SpecSection>

<SpecSection title="v0.3 delivery bands" id="v03-delivery-bands">
| Band | Content | Status |
| --- | --- | --- |
| **v0.3.0** | Interop views, link-time import, symbol overrides | Standard (spec); impl may trail |
| **v0.3.1** | `CLayout` primitive structs | Proposed |
| **Later** | Nested FFI structs, enum ABI, foreign-thread entry | Planned after basic FFI |
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- Extern import metadata: `compiler/crates/beskid_codegen/src/lowering/context.rs` (`ExternImport`)
- Collection: `compiler/crates/beskid_codegen/src/lowering/lowerable.rs`
- Contract calls: `compiler/crates/beskid_codegen/src/lowering/expressions/call_expression.rs`
- Signature validation: `compiler/crates/beskid_codegen/src/cranelift_host.rs`
- Legacy dynamic resolution: `compiler/crates/beskid_engine/src/engine.rs` (`extern_dlopen`, Proposed)
- Stable view layouts (embedding): `compiler/crates/beskid_abi/src/types.rs`
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-LMETA-CABI-0001` … `D-LMETA-CABI-0005`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [C ABI profile — C layout types (v0.3.1)](./articles/c-layout-types/)
- [C ABI profile — Dynamic resolution profile](./articles/dynamic-resolution-profile/)
- [C ABI profile — Extern contracts and linking](./articles/extern-contracts-and-linking/)
- [C ABI profile — Interop view types (v0.3.0)](./articles/interop-view-types/)
- [C ABI profile — Link-time linking](./articles/link-time-linking/)
- [C ABI profile — Platform tier matrix](./articles/platform-tier-matrix/)
- [C ABI profile — Types and call conventions](./articles/types-and-call-conventions/)
<!-- /spec:generate:article-index -->

## Context

Interop.Contracts primitives need a single C profile authority for tier-1 hosts.

## Decision

This feature hub **must** own normative MUST/SHOULD for **C-compatible** foreign libraries. Sibling articles add detail without redefining hub MUST tables.

## Consequences

Cranelift lowering and foreign library import tooling align to this profile.

## Verification anchors

/platform-spec/language-meta/interop/c-abi-profile/

## Context

Dynamic resolution complicates reproducible builds and CI conformance.

## Decision

v0.3 **Standard** tier-1 conformance **must** use **link-time** library binding ([link-time linking](/platform-spec/language-meta/interop/c-abi-profile/link-time-linking/)).

## Consequences

Engine may retain Proposed `extern_dlopen` paths separately from Standard claims.

## Verification anchors

`compiler/crates/beskid_codegen`; [Foreign library import](/platform-spec/tooling/foreign-library-import/).

## Context

Some hosts want late binding; tier-1 reference path standardizes link-time.

## Decision

**Runtime `dlopen` / `dlsym` resolution** is **demoted** to the [dynamic resolution profile](/platform-spec/language-meta/interop/c-abi-profile/dynamic-resolution-profile/) (**Proposed** appendix, not Standard).

## Consequences

Documentation and conformance matrices must not require dlopen for Standard tier-1.

## Verification anchors

`compiler/crates/beskid_engine/src/engine.rs` (`extern_dlopen`, Proposed).

## Context

WinAPI/stdcall surfaces belong in platform packages with distinct conformance tiers.

## Decision

**WinAPI / stdcall** as a **stdlib** concern is **out of scope** for tier-1 **Standard** conformance; platform packages may document **Proposed** mappings separately.

## Consequences

[Platform tier matrix](/platform-spec/language-meta/interop/c-abi-profile/platform-tier-matrix/) records host-specific tiers.

## Verification anchors

/platform-spec/language-meta/interop/c-abi-profile/

## Context

Implementers need a spec-first schedule when codegen trails text.

## Decision

| Band | Content | Status |
| --- | --- | --- |
| **v0.3.0** | Interop views, link-time import, symbol overrides | Standard (spec; impl may trail) |
| **v0.3.1** | `CLayout` primitive structs | Proposed |
| **Later** | Nested FFI structs, enum ABI, foreign-thread entry | Planned |

## Consequences

Articles tag Proposed vs Standard explicitly; CI strict mode can gate premature Standard claims.

## Verification anchors

/platform-spec/language-meta/interop/c-abi-profile/ and child articles.

> **Status: Proposed (v0.3.1)** — Normative text is stable for planning; reference compiler support **must** trail **[interop view types](./interop-view-types/)** (v0.3.0 Standard).

## Delivery order

1. **v0.3.0 Standard** — interop views, link-time import, export/callback registration.
2. **v0.3.1** — **`CLayout`** on Beskid `type` declarations for FFI-by-value structs with **primitive fields only**.
3. **Later** — nested records, enums with defined representation, arrays inside FFI structs, and WinAPI-specific calling conventions (not stdlib tier-1).

## `CLayout` attribute (planned)

```beskid
[CLayout(Align: 4)]
pub type WinSize {
    i32 ws_row,
    i32 ws_col,
    i32 ws_xpixel,
    i32 ws_ypixel,
}
```

| Rule | v0.3.1 |
| --- | --- |
| Field types | Primitives and other `CLayout` types only |
| Beskid `string` / `T[]` inside struct | **Forbidden** |
| Enums | **Forbidden** until discriminant/size rules exist |
| Alignment / pack | Explicit `Align` / `Pack`; default platform C rules |

## Complex types (explicitly later)

The platform **will** specify nested FFI structs, fixed-size array fields, and enum ABI **after** basic FFI (views + link + export) is implemented and covered by conformance tests. Until then, authors **must** use interop views, pointers as opaque `i64`, or thin C shims.

## Stdlib note

**WinAPI** and **stdcall** layouts are **out of scope** for standard library tier-1 packages. Windows-focused mappings may appear in optional platform packages under **Proposed** profiles, not as corelib **Standard** requirements.

> **Status: Proposed** — This profile is **not** required for v0.3 **Standard** conformance. It documents the reference engine’s optional **`extern_dlopen`** path for migration and tooling experiments.

## Behavior (reference)

When enabled on supported hosts (historically Linux x86_64):

- Libraries load via **`dlopen(RTLD_LOCAL | RTLD_NOW)`**.
- Symbols resolve via **`dlsym`** with process-lifetime caches.
- **`BESKID_EXTERN_ALLOW`** / **`BESKID_EXTERN_DENY`** apply as in `/execution/runtime/extern-policy-v0-1/`.

Implementation anchors: `compiler/crates/beskid_engine/src/engine.rs` (`extern_dlopen` feature).

## Relationship to v0.3 Standard

Production builds **should** use **[link-time linking](./link-time-linking/)**. Dynamic resolution remains available for:

- Local development without a full link driver.
- Tests gated by `--features extern_dlopen`.

## Deprecation direction

New platform-spec and CLI work **must** target link-time binding. Dynamic resolution **must not** be documented as the default in execution/runtime FFI chapters after v0.3.

## Extern metadata

User foreign entrypoints are declared on **`contract`** types using the **`Extern`** attribute (see **[FFI and extern](/platform-spec/language-meta/interop/ffi-and-extern/)**). The C ABI profile interprets attribute fields as:

- **`Abi`** — in current toolchains, **`"C"`** is the supported user-facing choice for this profile; other strings are reserved.
- **`Library`** — shared object or loadable module path semantics as implemented by the engine when dynamic resolution is enabled.

Implementation references: `ExternImport` in `compiler/crates/beskid_codegen/src/lowering/context.rs` and collection in `compiler/crates/beskid_codegen/src/lowering/lowerable.rs`.

## Link-time resolution (v0.3 Standard)

User **`Extern`** symbols **must** be satisfied at **link time** via project **`link`** metadata and driver inputs. See **[link-time linking](/platform-spec/language-meta/interop/c-abi-profile/link-time-linking/)** and **[foreign library import](/platform-spec/tooling/foreign-library-import/)**.

Artifacts with unresolved imports **must** fail before run with diagnostics listing `(library, symbol)` pairs.

## Dynamic resolution (non-Standard)

Runtime **`dlopen` / `dlsym`** is documented under **[dynamic resolution profile](/platform-spec/language-meta/interop/c-abi-profile/dynamic-resolution-profile/)** (Proposed). It **must not** be described as the default path in v0.3 platform-spec.

## AOT and JIT parity

Object emission paths **must** surface the same import set for a given artifact; unresolved symbols **must** fail at link time with parity between JIT link drivers and AOT link steps.

## Purpose

v0.3.0 introduces **interop view types**: transparent records with **stable C layout** used only at FFI boundaries. They align with runtime `repr(C)` helpers in `compiler/crates/beskid_abi/src/types.rs` without exposing GC-managed Beskid `string` or `T[]` directly.

Canonical definitions **should** live in corelib under an **`Interop`** package (exact package id is a corelib layout decision).

## Normative layouts (tier-1, 64-bit)

Layouts use pointer-sized fields in C ABI order.

### `CStringView`

UTF-8 byte range (does not imply null termination on the foreign side unless documented).

| Field | Type | Meaning |
| --- | --- | --- |
| `ptr` | pointer / `i64` | Start of bytes |
| `len` | `i64` | Byte length |

Maps to **`BeskidStr`** at the runtime embedding boundary.

### `CBuffer`

Read/write byte range.

| Field | Type | Meaning |
| --- | --- | --- |
| `ptr` | pointer / `i64` | Start of bytes |
| `len` | `i64` | Logical length |

### `CArrayView`

Fat-pointer compatible with runtime arrays.

| Field | Type | Meaning |
| --- | --- | --- |
| `ptr` | pointer / `i64` | Element storage |
| `len` | `i64` | Logical element count |
| `cap` | `i64` | Capacity |

Maps to **`BeskidArray`** where the profile documents element size separately.

## Permitted primitives (v0.3.0)

`bool` (as **`i8`** at boundary), `u8`, `i32`, `i64`, `f64`, `unit`, interop views above, and **`ref u8`** (legacy narrow slice start — prefer views).

## Lowering

The C ABI profile lowers views to a **flat list** of machine parameters per System V AMD64 (pointer and integer slots). The engine signature validator **must** accept only types expressible in that flat list.

## After basic FFI

**`CLayout` records** with primitive fields only arrive in **v0.3.1** ([C layout types](./c-layout-types/)). Nested structs, enums, and arrays inside FFI structs remain **deferred** until that band is stable.

## Standard conformance path

For **Standard** tier-1 conformance (System V AMD64 ELF hosts), user **`Extern`** symbols **must** be resolved at **link time** using:

1. **`Library`** strings on contracts (logical names).
2. Project **`link`** manifest metadata (see **[project link libraries](/platform-spec/tooling/manifests-and-lockfiles/project-manifest-contract/project-link-libraries/)**).
3. Driver-supplied linker inputs from **`beskid link`** / build commands and optional **[foreign library import](/platform-spec/tooling/foreign-library-import/)** mapping.

JIT and AOT backends **must** emit undefined symbols compatible with the platform linker for imports collected in **`ExternImport`**.

## Symbol identity

Link symbols use the method **`Symbol`** override when present; otherwise the Beskid method name. Name mangling **must not** apply to user extern symbols.

## Security

Link drivers **may** enforce **`BESKID_EXTERN_ALLOW`** / **`BESKID_EXTERN_DENY`** against resolved `(library, symbol)` pairs before producing a runnable artifact.

## JIT note

Reference JIT paths that relied on runtime **`dlopen`** are **not** the Standard story in v0.3. See **[dynamic resolution profile](./dynamic-resolution-profile/)** for the non-Standard appendix.

## AOT parity

AOT object emission **must** surface the same import set as JIT for a given artifact. Unresolved imports **must** fail at link time with actionable diagnostics listing missing symbols/libraries.

## Reference compiler status

On Linux tier-1, the AOT driver passes project `link.libraries` and discovered `ExternImport.library` values through `AotBuildRequest::external_libraries` (`compiler/crates/beskid_aot/src/api.rs`) and appends `-l<library>` / `-L<path>` in `compiler/crates/beskid_aot/src/linker.rs`. The engine consumer merges manifest link metadata in `compiler/crates/beskid_engine/src/link_libraries.rs`. Verification: `compiler/crates/beskid_engine/tests/ffi_v03_link_time.rs::link_time_extern_getpid_matches_platform_spec`.

## Tier-1 Standard (v0.3)

| Host | Calling convention | Linking | Stdlib foreign libs |
| --- | --- | --- | --- |
| Linux x86_64 ELF | System V AMD64 | Link-time | `libc`, `libpthread` class |
| macOS x86_64 / arm64 (POSIX) | Platform C ABI | Link-time | `libc`, `libSystem` class |

Reference compiler conformance claims **must** be justified against this matrix for user **`Extern`**.

## Proposed (not Standard in v0.3)

| Host | Notes |
| --- | --- |
| Windows x86_64 | **WinAPI / stdcall** — **out of scope for stdlib**. Optional platform packages may declare `Extern` contracts against `ucrtbase` / `kernel32` under a **Proposed** profile; not required for corelib **Standard**. |
| Dynamic-only resolution | **[Dynamic resolution profile](./dynamic-resolution-profile/)** |
| Foreign-thread callback entry | v0.3.2+ planning |

## Corelib policy

Standard library packages **must not** require WinAPI linkage for **Standard** conformance. Console and threading on Windows may ship as **optional platform packages** until a Proposed Windows profile is promoted.

Linux/macOS libc contracts in corelib remain the reference patterns for **`Extern`** documentation and tests.

## Calling convention

For user **`contract`** calls lowered through the reference compiler path, parameters and returns are prepared for **System V AMD64** when targeting that platform. This matches the explicit `CallConv::SystemV` selection in the contract call lowering implementation.

Other targets must document their own mapping in a future revision of this article; until then, only the documented tier-1 mapping is normative for **Standard** conformance claims.

## Permitted value shapes (v0.3.0)

The C ABI profile instantiates **[Interop.Contracts](/platform-spec/language-meta/interop/interop-contracts/)** as follows:

- **Scalar** — `bool` as **`i8`**, `u8`, `i32`, `i64`, `f64`, `unit`.
- **Interop views** — **`CStringView`**, **`CBuffer`**, **`CArrayView`** per **[interop view types](/platform-spec/language-meta/interop/c-abi-profile/interop-view-types/)**.
- **Opaque handle** — pointer-sized slot or `i64` where documented.
- **`ref u8`** — narrow legacy slice start; prefer **`CBuffer`**.

Beskid **`string`** and **`T[]`** GC values **must not** appear on user `Extern` signatures in v0.3.0 Standard.

**`CLayout` structs** (primitive fields only) are **v0.3.1** — **[C layout types](/platform-spec/language-meta/interop/c-abi-profile/c-layout-types/)**. Nested complex types are **deferred** until basic FFI is implemented.

Types with unstable Beskid-only layout **must not** cross the boundary without an adapter or shim.

## Cranelift note

Beskid user code and bridge code are lowered with **Cranelift**; foreign libraries need only expose **C ABI** entrypoints compatible with the emitted calls. See also `/execution/runtime/ffi/` for additional lowering narrative.