AILang/docs/specs/0055-intrinsic-bodies.md

Intrinsic bodies — Design Spec

Date: 2026-05-29 Status: Draft — awaiting user spec review Authors: orchestrator + Claude

Goal

Give Form-A a way to say "this definition's body is supplied by the compiler, not written in source" — and make that the single, honest representation for every definition whose real implementation lives in the codegen intercept registry (crates/ailang-codegen/src/intercepts.rs, shipped in raw-buf.1).

Today every such definition carries a dummy body that never runs. The prelude's eq Int instance method is

(module dummy_today
  (fn eq_int_like
    (doc "Real implementation is a codegen intercept; the body false never executes.")
    (type (fn-type (params (con Int) (con Int)) (ret (con Bool))))
    (params x y)
    (body false)))

The (body false) (and the eighteen siblings like it across the prelude) parses and type-checks, but codegen discards it and emits the intercept instead. The body is a structural lie: a reader who trusts the source is wrong about what runs. This is a standing infraction of the honesty rule (design/contracts/0007-honesty-rule.md), which the language has carried silently since the operator-routing milestone.

The lie is not merely cosmetic. It blocks the raw-buf milestone: a polymorphic kernel-tier function such as RawBuf's get : RawBuf a -> Int -> a needs a placeholder body that produces a value of type a — and AILang has no value of polymorphic type. There is no honest expression to write. The dummy-body requirement makes the function structurally impossible to author, which is what BLOCKED raw-buf.2 (see git log 4ad003d..647121c and the discarded .2 working tree).

The fix is a new Form-A surface affordance, (intrinsic), that replaces the (body ...) clause for compiler-supplied definitions. This is the same construct every systems language has: LLVM declare, Rust extern "rust-intrinsic" / #[rustc_intrinsic], Haskell foreign import prim, C compiler builtins. The intercept registry is AILang's compiler-supplied-body table; (intrinsic) is the surface declaration of membership in it.

Architecture

Three landing points, two iterations.

Iteration intrinsic-bodies.1 — the mechanism.

1. AST. A new leaf term variant Term::Intrinsic is the body of a compiler-supplied definition. FnDef.body and Term::Lam.body keep their existing types (Term / Box<Term>) — they are not made optional. A definition is intrinsic iff its body is Term::Intrinsic. The variant is strictly additive: a fixture that does not use it serialises bit-identically (the established additive-term-variant pattern — Term::New, Term::Loop, Term::Recur, Term::Clone, Term::ReuseAs all landed this way, design/contracts/0002-data-model.md). This is the load-bearing representation choice: it puts "this body is compiler-supplied" at the body position where it semantically belongs, keeps the ~150-site body-read/construct surface across six crates untouched (only exhaustive match-on-Term arms gain a case), and makes the illegal "body AND intrinsic" state unrepresentable rather than rejected — a body is either Term::Intrinsic or a real term, never both. (The rejected alternative, body: Option<Term> + an intrinsic: bool flag, splits one fact across two fields, admits that illegal state, and breaks every body consumer in the workspace.)
2. Form-A surface. For a top-level fn, the parser accepts (intrinsic) as a sibling clause where (body ...) would go and maps it to body = Term::Intrinsic; the printer emits (intrinsic) in that slot when the body is Term::Intrinsic. For a lambda, (intrinsic) sits at the positional body slot (where the body term goes today) and parses to Term::Intrinsic; the printer emits it there. Round-trip (parse ∘ print = id) holds by the standard fixture gate. The fn-vs-lam surface asymmetry mirrors the existing one (a fn carries a named (body X) clause; a lambda carries its body positionally) — (intrinsic) follows each form's existing body placement.
3. Checker. A definition whose body is Term::Intrinsic type-checks against its signature only — there is no body term to infer. One new reject: an intrinsic definition outside a (kernel)-tier module or the prelude is rejected with intrinsic-outside-kernel-tier. (There is no intrinsic-with-body reject — the representation makes that state impossible, see point 1.)
4. Codegen. A definition whose body is Term::Intrinsic routes through intercepts::lookup; if no intercept is registered for its mangled name, codegen emits the existing deferral diagnostic. The current "lower the body" path is not taken for these definitions — lower_term is never called on a Term::Intrinsic body (and a Term::Intrinsic reaching lower_term through any other path is a codegen-internal error, since an intrinsic body must be consumed by the intercept route).
5. Ratifier. One throwaway intrinsic in the kernel_stub fixture — a nullary answer : () -> Int whose intercept emits ret i64 42 — drives the mechanism end-to-end (parse → check → codegen → run). kernel_stub already exists precisely to ratify kernel-tier mechanisms.

Iteration intrinsic-bodies.2 — the migration + the lock.

6. Prelude migration. The thirteen authored dummy bodies in examples/prelude.ail swap their inner (body <dummy>) for (intrinsic): the seven Eq/Ord instance methods (eq for Int/Bool/Str/Unit, compare for Int/Bool/Str) and the six float_* free fns (float_eq/ne/lt/le/gt/ge). These are exactly the INTERCEPTS entries that today carry a placeholder body a reader would mistake for the implementation.

   Not migrated, and why (the count reconciliation — the registry has nineteen entries, not eighteen-all-dummies):

   • lt__Int, le__Int, gt__Int, ge__Int, ne__Int (5) intercept the monomorphised __Int specialisations of the polymorphic free fns lt/le/gt/ge/ne, which carry real bodies in the prelude ((match (app compare x y) …), (app not (app eq x y))). Those bodies are honest and live — they are lowered for every non-Int instantiation; only the Int specialisation is intercepted for a faster direct icmp. These are an optimisation class, not a compiler-supplied-body class: there is no lie to fix and no source body to replace, so they get no (intrinsic) marker.
   • answer (1) is the .1 ratifier, already (intrinsic) in STUB_AIL — not a prelude site.

   So: 13 prelude migrations + 5 optimisation-class entries + 1 already migrated = 19 INTERCEPTS entries.

7. Hard-lockstep pin. The registry splits into two classes: an entry is intrinsic-backed when a (intrinsic) marker in the loaded workspace resolves to its mangled name (the 13 prelude migrations + answer = 14), or optimisation-only when it intercepts a real-bodied fn's specialisation (the 5 *__Int icmp family). The pin asserts a bijection over the intrinsic-backed class: every workspace (intrinsic) marker has exactly one INTERCEPTS entry, and every INTERCEPTS entry not on the explicit optimisation-only allowlist has exactly one workspace marker. The optimisation-only set is an explicit, documented allowlist in the pin (the 5 names); adding a registry entry that is neither marker-backed nor allowlisted is a red test, as is an intrinsic marker with no entry. This extends the registry_contains_all_legacy_arms pin from raw-buf.1 from a one-directional name check to a two-directional source↔registry bijection.

8. Dead-path confirmation. .1 already routes every intercepted def by name (try_emit_primitive_instance_body consults intercepts::lookup on the fn name before the body is inspected), so a prelude dummy body is bypassed before it could reach lower_term — the dummy is already dead, not lowered-then-discarded. After migration the dummy is gone entirely (replaced by Term::Intrinsic). This point is therefore a verification, not a removal: confirm no codegen path lowers an intercepted body, and delete now-stale comments that reference the discarded dummy. The Term::Intrinsic internal-error guards in lower_term / the synth walker (added in .1) STAY — they guard against an intrinsic body escaping its definition slot, which is a different concern.

Concrete code shapes

North-star: what a kernel author writes (proposed surface)

The surface this milestone delivers. These blocks are labelled scheme (not ail) on purpose — the (intrinsic) attribute does not parse against the pre-feature tool, so they are proposals, not ratified current behaviour. (Verified: see the must-fail transcript below.)

The raw-buf north-star — a polymorphic kernel-tier function with no honest body, the case that motivated the milestone:

(fn get
  (doc "Indexed read. Codegen intercept get__RawBuf__<T> emits a getelementptr + load.")
  (type (forall (vars a) (fn-type (params (borrow (con RawBuf a)) (con Int)) (ret (con a)))))
  (params b i)
  (intrinsic))

The prelude eq Int instance method after migration (the lie, fixed). The marker sits on the lambda body; the lambda's typed shell (params/ret) stays — it is the method's local signature, and intrinsic drops the body, not the signature (see the rationale under "Implementation shape" below):

(instance
  (class Eq)
  (type (con Int))
  (doc "Eq Int. Codegen intercept eq__Int emits icmp eq i64 with alwaysinline.")
  (method eq
    (body (lam (params (typed x a) (typed y a)) (ret (con Bool)) (intrinsic)))))

The intrinsic-bodies.1 ratifier — the throwaway smoke intrinsic in the kernel_stub fixture:

(fn answer
  (doc "Ratifies the intrinsic mechanism end-to-end. Intercept answer emits ret i64 42.")
  (type (fn-type (params) (ret (con Int))))
  (params)
  (intrinsic))

Current-state evidence (parses today)

The dummy-body lie exactly as the prelude carries it now — a body that parses, type-checks, and never runs:

(module dummy_today
  (fn forty_two
    (doc "Real implementation is a codegen intercept. The body 0 never executes.")
    (type (fn-type (params (con Int)) (ret (con Int))))
    (params n)
    (body 0)))

Must-fail evidence (rejected today)

(intrinsic) is not yet a surface attribute, so the proposed forms above are rejected by the pre-feature tool. This is the baseline the milestone moves off — the parser reject is what intrinsic-bodies.1 turns into an accept (inside kernel-tier / prelude) and a different reject (intrinsic-outside-kernel-tier, for user modules):

$ cat intr.ail
(module intr
  (fn new (type (fn-type (params (con Int)) (ret (con Int)))) (params n) (intrinsic)))
$ ail check intr.ail
error: [surface-parse-error] parse error in fn-def: unknown fn attribute
  `intrinsic`; expected `doc`, `export`, `suppress`, `type`, `params`,
  or `body` at byte 86

Implementation shape (secondary — the AST delta)

The change is one new leaf Term variant. Exact bytes are the planner's job; this fixes the shape only.

Term::Intrinsic (crates/ailang-core/src/ast.rs):

// new leaf term — the body of a compiler-supplied definition.
// Strictly additive (no skip_serializing_if needed; a fixture that
// does not carry it hashes bit-identically — the same additive-variant
// pattern as Term::New / Term::Loop / Term::Recur / Term::Clone).
// Never reduces to a value: codegen consumes it via intercepts::lookup,
// the typechecker treats a def with this body as signature-only.
{ "t": "intrinsic" }

FnDef.body (currently Term) and Term::Lam.body (currently Box<Term>) are unchanged in type — they simply may now hold Term::Intrinsic. A top-level intrinsic fn is FnDef { body: Term::Intrinsic, .. }; an intrinsic instance-method lambda is Term::Lam { body: Box::new(Term::Intrinsic), .. }. "Is this definition intrinsic?" is matches!(body, Term::Intrinsic).

The marker sits at the body position — for a top-level fn that is the fn body; for an instance method that is the lambda body, not the method as a whole — and this placement is load-bearing, not incidental.

The reason is local reasoning (design/INDEX.md § Goal: "every definition carries its full type and effect set, so a signature can be trusted without reading the body"). An intrinsic is a signature without a body, never nothing — exactly as LLVM declare i64 @llvm.foo(i64, i64), Rust extern "rust-intrinsic" { fn foo(x: i32) -> i32; }, and Haskell foreign import prim all keep the full signature and drop only the body. For a top-level fn the signature is the (type ...) clause, which stays beside the (intrinsic) marker. For an instance method the signature-bearing structure is the lambda itself: its (params (typed x a) (typed y a)) and (ret (con Bool)) are the parameter types and return type, readable at the definition site. Hoisting the marker to the method ((method eq (intrinsic))) would erase that local signature — a reader would have to climb to the Eq class declaration and substitute a := Int mentally to recover it. So the marker is the lambda's body (Term::Intrinsic), leaving the lambda's typed shell — the local signature — in place. The mono pass (crates/ailang-check/src/mono.rs::synthesise_mono_fn) already reads the method's parameter names and inner body out of this lambda (Term::Lam { params, body, .. } => (params, *body)); with the inner body being Term::Intrinsic, the synthesised FnDef carries body: Term::Intrinsic and is itself intrinsic. The destructure itself is unchanged — only what the inner body is differs.

Hash-stability note: Term::Intrinsic is a new enum variant, not a new field, so a fixture that does not use it serialises exactly as before — the same mechanism that kept hashes stable when Term::New, Term::Loop, and Term::Recur were added. The design_schema_drift.rs schema mirror, the schema_coverage.rs variant corpus (a fixture must now exercise Term::Intrinsic), and the 0002-data-model.md contract all move in the same iteration as the variant.

Components

Component	Iteration	Change
crates/ailang-core/src/ast.rs	.1	New leaf variant Term::Intrinsic. FnDef.body / Lam.body types unchanged.
crates/ailang-core canonical/hash/visit	.1	Exhaustive match-on-Term arms gain a Term::Intrinsic case (leaf, no sub-terms to walk). Schema-coverage corpus extended to exercise it.
crates/ailang-surface (lex/parse/print)	.1	(intrinsic) parsed + printed: as a body-slot clause in fn-def, at the positional body slot in lam; maps to/from Term::Intrinsic; round-trip gated.
crates/ailang-check/src/lib.rs	.1	A def whose body is Term::Intrinsic checks signature-only; rejects intrinsic outside kernel-tier/prelude (intrinsic-outside-kernel-tier). No intrinsic-with-body reject — the representation forbids that state.
crates/ailang-check/src/mono.rs	.1	synthesise_mono_fn lambda-destructure unchanged; an inner Term::Intrinsic body flows through to an intrinsic synthesised FnDef.
crates/ailang-codegen/src/lib.rs	.1	A def whose body is Term::Intrinsic routes through intercepts::lookup; lower_term is never called on it.
crates/ailang-kernel-stub + ailang-surface parse hop	.1	answer smoke intrinsic added to the stub fixture; its intercept registered.
examples/prelude.ail	.2	13 authored dummy bodies → (intrinsic) (7 Eq/Ord instance methods + 6 float_* fns). The 5 *__Int icmp-family and answer are NOT prelude sites.
crates/ailang-codegen/src/intercepts.rs (pin)	.2	registry_contains_all_legacy_arms upgraded to a bijection over the intrinsic-backed class + an explicit 5-name optimisation-only allowlist. Pin loads the workspace + monomorphises to recover mangled names for the marker direction.
crates/ailang-surface/tests/prelude_module_hash_pin.rs	.2	Rebaseline the prelude module hash (13 bodies change).
crates/ail/tests/mono_hash_stability.rs	.2	Rebaseline the 6 post-mono eq__*/compare__* def-hashes (body flips to Term::Intrinsic). The 4 show__* pins do NOT move.
codegen dummy-body path	.2	Already dead post-.1 (intercept-by-name precedes body inspection); .2 confirms + deletes stale comments, no behavioural removal.
design/contracts/0002-data-model.md	.1	New { "t": "intrinsic" } Term entry; note in fn/lam that the body may be Term::Intrinsic.
design/contracts/0007-honesty-rule.md	.2	Edit only if it names the prelude dummies; recon found it is a general rule that may not reference them — flag honestly, no forced edit.

Data flow

Authoring → parse → AST → check → codegen, unchanged in topology; Term::Intrinsic is recognised at three of those stations:

1. Parse. (intrinsic) in a fn body slot or a lambda body slot produces a Term::Intrinsic body. There is no "both body and intrinsic" surface form to reject — the grammar offers one body slot, and (intrinsic) either fills it or it does not.
2. Check. A def whose body is Term::Intrinsic: validate the signature, skip body inference. Enforce the kernel-tier/prelude scope. The module's kernel: true flag (or prelude identity) is already available to the checker via the loaded workspace.
3. Codegen. A def whose body is Term::Intrinsic: intercepts::lookup(mangled_name). Hit → emit the intercept. Miss → the existing deferral diagnostic (same one raw-buf.2 reuses for unregistered RawBuf ops).

Error handling

Condition	Diagnostic	Station
(intrinsic) in a non-kernel, non-prelude module	intrinsic-outside-kernel-tier	check
Intrinsic def with no registered intercept	existing codegen deferral	codegen

The first row is the honesty-rule guard at the workspace boundary: user code cannot mark a body as compiler-supplied, so the lie cannot re-enter through user modules. (There is deliberately no "body-and-intrinsic" row — Term::Intrinsic is a body, so a def either has it or has a real body, never both. The illegal state is unrepresentable, not diagnosed.)

Testing strategy

intrinsic-bodies.1:

• Round-trip: a kernel-tier fixture carrying (intrinsic) on both a top-level fn and a lambda parses → prints → re-parses to canonical-byte equality (rides the existing round_trip.rs corpus gate).
• Check accept: the kernel_stub answer intrinsic checks clean.
• Check reject (scope): a user module with an (intrinsic) fn is rejected with intrinsic-outside-kernel-tier.
• E2E: answer builds and runs, exit/print observing 42 — the mechanism works from source to native.
• Schema drift: design_schema_drift.rs green against the new 0002-data-model.md; schema_coverage.rs observes Term::Intrinsic in the fixture corpus.

intrinsic-bodies.2:

• Hard-lockstep pin: bijection over the intrinsic-backed class. Add an intrinsic marker with no INTERCEPTS entry → red; add a non-allowlisted INTERCEPTS entry with no marker → red; drop either → red. The 5-name optimisation-only allowlist is explicit in the pin; the pin loads the workspace, monomorphises, and walks post-mono FnDef bodies for Term::Intrinsic to recover mangled names for the marker direction.
• All pre-existing E2E ratifiers stay green (the eq/compare/float smoke suite named in raw-buf.1's commit body: eq_primitives_smoke_compiles_and_runs, compare_primitives_smoke_prints_1_2_3_thrice, float_compare_smoke_prints_true_true_false, eq_ord_polymorphic_runs_end_to_end) — the migration is behaviour-preserving (the intercepts emit the same IR; only the now-dead source body changes).
• Hash rebaselines (both move; both recorded old→new in the commit body): prelude_module_hash_pin.rs (prelude module hash; 13 bodies change) and mono_hash_stability.rs (the 6 post-mono eq__*/compare__* def-hashes flip to Term::Intrinsic; the 4 show__* pins do NOT move). IR snapshots do NOT change (no prelude instance method is codegen'd into the user-program snapshots).

Acceptance criteria

Applied prospectively (design/contracts/0004-feature-acceptance.md):

• An LLM author naturally reaches for it. A kernel author writing RawBuf.get has no honest body to write — there is no value of type a. Faced with the dummy-body requirement, the natural move is to declare "the compiler supplies this", which is exactly (intrinsic). The north-star block above is that program; it is the empirical evidence, not a prose assertion.
• Measurably improves correctness / removes redundancy. Closes a standing honesty-rule infraction (eighteen bodies that lie about what runs); removes the dead body-lowering path for intercepted defs; removes the structural impossibility blocking polymorphic kernel-tier functions.
• Reintroduces no eliminated failure class. Machine-readability, local reasoning, provability, hallucination-robustness all hold or improve: a reader of an (intrinsic) def now knows from the source alone that the body is compiler-supplied, instead of having to read the codegen table to discover the source was lying.

Out of scope: a user-facing plugin API for registering custom intercepts (the scope guard explicitly forbids (intrinsic) in user modules); any change to the intercept dispatch mechanism shipped in raw-buf.1; the raw-buf redo itself (a separate milestone that consumes this one).