Design the stable C-ABI embedding surface

Summary

Design the stable C ABI exported by the versioned libgoccia dynamic library. The ABI lets C, Rust, Zig, C++, Crystal, Nim, and C# hosts create an engine, run source, call functions, exchange values, and manage value lifetime across the boundary. Design-only; it gates #865, #866, and #867.

Why

The vision includes desktop embedding, but the only embedding path today is FreePascal-native through TGocciaEngine and TGocciaRuntime. Current source has no Pascal library/exports boundary; existing dynamic-library code is inbound FFI rather than an exported host API.

Current behavior

• Embedding requires direct use of Pascal engine units.
• Values are GC-managed Pascal objects and rooting is explicit.
• Each engine owns its realm; GC, call stack, and microtask queue are thread-local.
• No exported symbols, ABI version query, C header, or dynamic-library lifecycle exists.

Expected behavior

Define and document:

• ABI/version discovery suitable for a versioned libgoccia dynamic library.
• Lifecycle: engine creation/free, runtime-profile selection, and execution limits.
• Execution: source evaluation and callable invocation with marshalled arguments.
• Opaque value handles with goccia_value_ref and goccia_value_unref mapped onto GC roots.
• Accessors and constructors for number, UTF-8 string, boolean, null, undefined, arrays, and objects, plus an explicit BigInt/Symbol policy.
• Status-code and structured-error reporting so Pascal exceptions never cross the ABI.
• Single-thread affinity for each engine handle.
• Symbol visibility and compatibility rules for adding, deprecating, and removing exported functions.

Scope notes

• Design-only. Implementation #865, validation #866, documentation #867.
• Per-language idiomatic wrappers are downstream of the flat C ABI.
• Record the handle-table, versioning, ownership, error, and thread-affinity decisions in an ADR during implementation.
• Parent #823; related cross-compilation work #238.
• A static library is not part of this track.

Start by reading the Pascal TGocciaEngine and TGocciaRuntime units and the existing inbound FFI code described in the issue. Define the ABI, ownership, error, versioning, and thread-affinity decisions in an ADR. Done means the stable C embedding surface is documented well enough to guide implementation #865 and validation #866.