<SpecSection title="What this feature specifies" id="what-this-feature-specifies">
**Export and callbacks** defines how Beskid code **exposes** entrypoints to foreign hosts (plugins, embedders, C drivers) and how **function-pointer callbacks** are registered for re-entry.

This is **user interop**, not the frozen **runtime builtin** table on the **[Rust ABI profile](/platform-spec/language-meta/interop/rust-abi-profile/)**. Export symbols are **generated** from Beskid compilation units; runtime builtins remain **`beskid_abi`** exports.
</SpecSection>

<SpecSection title="v0.3 scope" id="v03-scope">
| In scope | Out of scope |
| --- | --- |
| **`[Export]`** on **`pub` functions** with FFI-permitted types | Exporting arbitrary `contract` vtables as Standard |
| **Callback registration** table protocol | Foreign-thread entry without host contract (Proposed v0.3.2+) |
| **Trampolines** for GC-safe re-entry | Changing `BESKID_RUNTIME_ABI_VERSION` for export-only features |

Spec is **Standard** in v0.3; reference compiler support for export lowering, callback registration, and link-time extern resolution is landed on Linux tier-1 (see **[verification](./verification-and-traceability/)**).
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- Export metadata in `compiler/crates/beskid_codegen/src/lowering/expressions/export.rs` and `compiler/crates/beskid_codegen/src/lowering/context.rs` (`CodegenArtifact::exports`)
- AOT export table and linker export policy: `compiler/crates/beskid_aot/src/export_table.rs`
- Callback registration and GC-safe trampolines: `compiler/crates/beskid_runtime/src/builtins/callback.rs` (`beskid_register_callbacks`, `BESKID_USER_FFI_LAYOUT_BAND` in `compiler/crates/beskid_abi/src/symbols.rs`)
- Optional extension of `interop_dispatch_*` for typed host callbacks (reserved; not user `Extern`)
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
No open decisions. Closed choices are normative ADRs under **`adr/`** (`D-LMETA-EXPORT-0001` … `D-LMETA-EXPORT-0004`); use the reader **ADRs** tab for expandable detail.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Callback registration](./articles/callback-registration/)
- [Export attribute](./articles/export-attribute/)
- [Export and callbacks — Verification and traceability](./articles/verification-and-traceability/)
<!-- /spec:generate:article-index -->

## Context

Export/callback rules were scattered between runtime and language-meta drafts.

## Decision

This feature hub **must** own normative MUST/SHOULD for Beskid **export** and **callback registration** (user interop).

## Consequences

Distinct from runtime builtin exports on Rust ABI profile.

## Verification anchors

/platform-spec/language-meta/interop/export-and-callbacks/

## Context

Plugin authors confused generated exports with frozen JIT builtin tables.

## Decision

User **export** symbols are **generated** from Beskid compilation units. Frozen **runtime builtin** exports remain on **`beskid_abi`** / **[Rust ABI profile](/platform-spec/language-meta/interop/rust-abi-profile/)** — export-only work **must not** change `BESKID_RUNTIME_ABI_VERSION`.

## Consequences

Codegen plans export metadata beside `ExternImport`; trampolines use runtime TLS hooks.

## Verification anchors

/platform-spec/language-meta/interop/export-and-callbacks/ implementation anchors.

## Context

Embedding hosts need a minimal stable export surface before full vtable stories.

## Decision

v0.3 Standard **must** support **`[Export]`** on **`pub` functions** with FFI-permitted types. Exporting arbitrary **`contract`** vtables as Standard is **out of scope** for v0.3.

## Consequences

Callback registration table protocol is Standard; foreign-thread entry without host contract is Proposed v0.3.2+.

## Verification anchors

[export attribute](/platform-spec/language-meta/interop/export-and-callbacks/export-attribute/); [callback registration](/platform-spec/language-meta/interop/export-and-callbacks/callback-registration/).

## Context

v0.3 is spec-first for interop; codegen for export is still landing.

## Decision

This feature is **Standard** in v0.3 specification. Reference compiler support **may** trail; verification article records gaps until codegen lands.

## Consequences

Contributors implement against ADRs without downgrading spec status to Proposed.

## Verification anchors

[verification and traceability](/platform-spec/language-meta/interop/export-and-callbacks/verification-and-traceability/).

## Model

Foreign hosts (game engines, shells, OS services) register Beskid **callbacks** before or during runtime. v0.3 Standard defines:

1. **Exported Beskid functions** — normal `[Export]` entrypoints.
2. **Registration contract** — a Beskid `contract` describing callback function-pointer types the host implements or consumes.
3. **Registration export** — a stable C symbol the host calls to install a table of function pointers.

## Registration export (normative shape)

The platform reserves a runtime or generated symbol (exact name is toolchain-defined; example):

```text
beskid_register_callbacks(version: u32, table: *const CallbackTable, count: usize) -> i32
```

| Field | Meaning |
| --- | --- |
| `version` | **User FFI layout band** — must match `BESKID_USER_FFI_LAYOUT_BAND` |
| `table` | Array of `{ symbol_id, fn_ptr, userdata }` rows |
| `count` | Number of rows |
| Return | `0` success; non-zero stable error codes |

Hosts **must** reject unknown `version` values.

## Reference symbol

The reference runtime exposes `beskid_register_callbacks` from `compiler/crates/beskid_runtime/src/builtins/callback.rs`, registered in `RUNTIME_EXPORT_SYMBOLS` and `BUILTIN_SPECS` via `compiler/crates/beskid_abi/src/symbols.rs`. Hosts **must** pass `version == BESKID_USER_FFI_LAYOUT_BAND` (initial Standard value `1`).

## Beskid-side callback exports

Each callback slot points at a **`[Export(Abi:"C")]`** function or a **compiler-generated trampoline** that:

- Enters runtime TLS / heap scope.
- Performs any GC safepoint policy required before executing Beskid code.
- Maps parameters from C layout to Beskid types.

## Import-side function pointers

`Extern` contracts **may** accept function-pointer parameters when the pointee is a documented **`Export`** or trampoline symbol. See **[callback call shapes](/platform-spec/language-meta/interop/interop-contracts/callback-call-shapes/)**.

## Non-goals (v0.3)

- Automatic binding generation from C headers.
- Foreign-thread callback without host lifecycle contract (Proposed later).

## Placement

**`Export`** applies to **`pub` function definitions** only in v0.3 Standard. Contract methods, types, and modules **must not** use **`Export`** until a future profile promotes contract vtables.

## Attribute fields

| Field | Required | Meaning |
| --- | --- | --- |
| **`Abi`** | yes | **`"C"`** for v0.3 Standard |
| **`Symbol`** | no | Exported linker symbol; default is the Beskid function name (unmangled) |

Example:

```beskid
[Export(Abi:"C", Symbol:"beskid_plugin_init")]
pub i64 plugin_init(i64 host_api_version) {
    return 0;
}
```

## Permitted signatures

Export functions **must** use the same type set as **`Extern`** import methods in v0.3.0 ([interop view types](/platform-spec/language-meta/interop/c-abi-profile/interop-view-types/)).

## Linkage

Exported symbols **must** be emitted with global linkage visible to the platform linker. The build driver **must** include Beskid-generated objects and the runtime static archive per backend docs.

## Panics

Panics in exported functions **must** be treated as **non-returning traps** across the boundary ([error and unwind](/platform-spec/language-meta/interop/interop-contracts/error-and-unwind-semantics/)).

## Reference compiler status

| Surface | Status | Primary verification |
| --- | --- | --- |
| `[Export(Abi:"C", Symbol:"...")]` on `pub fn` | Implemented (codegen + AOT) | `compiler/crates/beskid_engine/tests/ffi_v03_link_time.rs::export_plugin_init_visible_to_linker` |
| Callback registration `beskid_register_callbacks` + layout band | Implemented (runtime export) | `compiler/crates/beskid_engine/tests/ffi_v03_link_time.rs::host_registers_callbacks_with_layout_band` |
| Link-time `Extern` via project `link` / `external_libraries` | Implemented (AOT linker, Linux tier-1) | `compiler/crates/beskid_engine/tests/ffi_v03_link_time.rs::link_time_extern_getpid_matches_platform_spec` |
| `Export` on non-`pub` function | Codegen diagnostic | `compiler/crates/beskid_tests/src/interop/export.rs::export_on_non_pub_function_fails_codegen` |

## Verification anchors

- Engine (Linux tier-1): `compiler/crates/beskid_engine/tests/ffi_v03_link_time.rs` — link-time `getpid`, shared-library export visibility, callback layout-band gate.
- Integration: `compiler/crates/beskid_tests/src/interop/export.rs`, `compiler/crates/beskid_tests/src/interop/callback.rs`.
- Codegen export metadata: `compiler/crates/beskid_codegen/src/lowering/expressions/export.rs`, `compiler/crates/beskid_codegen/src/lowering/context.rs` (`CodegenArtifact::exports`).
- AOT export table: `compiler/crates/beskid_aot/src/export_table.rs`.
- Runtime callback registration: `compiler/crates/beskid_runtime/src/builtins/callback.rs` (`beskid_register_callbacks`).
- ABI symbols: `compiler/crates/beskid_abi/src/symbols.rs` (`SYM_BESKID_REGISTER_CALLBACKS`, `BESKID_USER_FFI_LAYOUT_BAND`), `compiler/crates/beskid_abi/src/builtins.rs` (`BUILTIN_SPECS`).

## Runtime ABI

Adding **user export symbols** **must not** change `RUNTIME_EXPORT_SYMBOLS` unless a new **runtime-provided** registrar is promoted to the Rust ABI profile. `beskid_register_callbacks` is a runtime export for host registration; user `[Export]` symbols remain generated from Beskid compilation units.