Brummel
176821c2e7
The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.
RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.
Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.
Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# Embedding ABI
|
|
|
|
## Embedding ABI
|
|
|
|
`ail build --emit=staticlib` compiles a module to a relocatable
|
|
`lib<entry>.a` (program objects only) plus a separate
|
|
`libailang_rt.a` (the RC runtime: `rc.c` + `str.c`), with **no**
|
|
`@main` trampoline and **no** `MissingEntryMain` requirement — a
|
|
kernel module is a library.
|
|
|
|
Each `fn` carrying `(export "<sym>")` (schema: `FnDef.export`) is
|
|
emitted as an externally-visible C entrypoint `@<sym>` forwarding to
|
|
the internal `@ail_<module>_<fn>`. The symbol is author-chosen and
|
|
decoupled from the `ail_<module>_<def>` mangling so a module/fn
|
|
rename does not move the C symbol.
|
|
|
|
The set that can cross the boundary is exactly: `Int` (lowered
|
|
`i64`), `Float` (lowered `double`), or a single-constructor record
|
|
whose every field is one of those (crossing as a bare `ptr` to the
|
|
box layout below); the fn's effect set must be empty. There is no
|
|
general value-marshalling layer — the host hand-constructs and
|
|
hand-reads that box layout directly, so the enumerated set *is* the
|
|
whole contract, narrow by construction, not a subset of a wider
|
|
embedding ABI. Because the box layout is the host's contract
|
|
surface with no accessor indirection, it is a **one-way commitment
|
|
frozen as of M3**: a compiler change MUST NOT move the box offsets
|
|
below for an exported type, nor invert the host-free rule.
|
|
These are enforced at `ail check` (`export-non-scalar-signature`,
|
|
`export-has-effects`) — an effectful or non-scalar export *fails to
|
|
typecheck*. Every exported entrypoint takes a mandatory leading `ailang_ctx_t*`
|
|
(M2): a per-thread embedding context created by `ailang_ctx_new()`
|
|
and released by `ailang_ctx_free()`, owned by the calling thread for
|
|
its lifetime. The host links one `ailang_ctx_t` per OS worker thread
|
|
and the runtime accounts RC alloc/free into it: the per-allocation
|
|
hot path (the per-ctx counters and the per-object refcount header)
|
|
is non-atomic by design and never shared — a box never crosses a
|
|
thread (`Ctx: !Send`) and each `ailang_ctx_t` is
|
|
single-thread-per-ctx. The one datum a multi-threaded host shares
|
|
is the global RC-stats fallback counter (used when no ctx is
|
|
bound); it is atomic-relaxed so the swarm's leak accounting is
|
|
exact. The swarm artefact is data-race-free, sanitiser-verified.
|
|
The staticlib swarm artefact is **RC-only**:
|
|
`ail build --emit=staticlib` rejects `--alloc=gc`/`--alloc=bump`
|
|
(the shared Boehm collector is not swarm-safe). The value/record
|
|
layout is **frozen as of M3** (see "Frozen value layout" below); the
|
|
ctx-threaded C signature is the M2 shape.
|
|
|
|
Export parameters are written **bare**: a scalar type carries no
|
|
`own`/`borrow` mode (a single-constructor record export parameter,
|
|
by contrast, carries `own`/`borrow` — the ownership contract the
|
|
frozen value layout below specifies). The
|
|
canonical M1 export shape:
|
|
|
|
```
|
|
(fn step
|
|
(export "backtest_step")
|
|
(type
|
|
(fn-type
|
|
(params (con Int) (con Int))
|
|
(ret (con Int))))
|
|
(params state sample)
|
|
(body
|
|
(app + state (app * sample sample))))
|
|
```
|
|
|
|
`ail emit-ir <module> --emit=staticlib` prints this kernel's LLVM
|
|
IR (the external `@<sym>` forwarders, no `@main`) instead of the
|
|
executable-path `main`-required rejection — the Decision-5
|
|
IR-readability affordance for a `main`-free kernel.
|
|
|
|
Ratified by: `crates/ailang-codegen/tests/embed_record_layout_pin.rs`.
|