Repository navigation
Description
Summary
Typed bindings for the Erlang FFI: extern module declarations, a BEAM-shape type vocabulary, arity and argument checking at foreign call sites, using for foreign paths, declaration generation from OTP specs, and Hex packages as a dependency kind.
Current state
The FFI itself works — Erlang.Lists.reverse([1,2,3]) compiles to call 'lists':'reverse' and runs. But:
- Every foreign call is untyped.
src/semantic/typechecker.cxx:3149-3162short-circuits any call rooted atErlang/Elixir/Gleamand returnsType::unknown(). Nothing checks arity, argument types, or the result — an arity mistake isundefat runtime with no source location. usingdoes not reach foreign modules.using Erlang.Listswarnsmodule not found in source roots, and the prefix must be repeated at every call site.- The walker cannot do it at all.
Erlang.Lists.reverseunder the default backend reportsUndefined function: Erlang.Lists, which reads like a typo.
Core design decisions
- Declarations describe BEAM shapes, never Kex shapes. A foreign signature says
Charlist, notString— KexStringis a binary, whileErlang.Erlang.system_info(:otp_release)returns[50, 57]. Adaptation is ordinary Kex code in a wrapper. A declaration claimingsystem_info : Atom -> Stringwould be a lie that surfaces as[50, 57]in output orbadargseveral frames deeper — not as a type error. - No new file format. Declarations are ordinary
.kexsource; a declarations-only package is an ordinary package with no runtime code. - Opt-in and additive. An undeclared foreign module keeps working exactly as today, at
Unknown. - A declaration is trusted, and can be wrong —
unsafein the Rust sense. The mitigation is a debug-mode contract check, not a proof. - Foreign calls stay BEAM-only. The walker gets a diagnostic, not an implementation.
- No implicit build scripts. Compiling plain
.erlwitherlcourselves is not an install script; runningmixis, and needs to be asked for out loud.
The type vocabulary
| Name | BEAM value | Notes |
|---|---|---|
Binary |
binary | what Kex String already is; the only free conversion |
Charlist |
list of codepoints | needs list_to_binary |
ErlAtom |
atom | distinct from Kex Atom's naming rules |
ErlList<T> |
proper list | element types may need mapping |
ErlTuple<A, B, ...> |
tuple | fixed arity |
ErlMap<K, V> |
map | |
Pid, Ref, Port, Fun |
opaque | no operations except passing back |
ErlTerm |
anything | the honest Unknown; explicit rather than inferred |
ErlResult<T> |
{ok, T} | {error, term()} |
the Erlang convention, not Kex's Result |
ErlBool |
true | false atoms |
coincides with Kex Bool, converts freely |
The declaration form
extern module Erlang.Lists do
reverse : ErlList<ErlTerm> -> ErlList<ErlTerm>
sum : ErlList<Integer> -> Integer
seq : (Integer, Integer) -> ErlList<Integer>
end
extern module Erlang.GenServer, atom: "gen_server" do
call : (Pid, ErlTerm) -> ErlTerm
start_link : (ErlAtom, ErlTerm, ErlList<ErlTerm>) -> ErlResult<Pid>
end
The atom: override fixes the Erlang.Gen_server wart: underscored module names must be written with exactly one capital (Gen_server, not GenServer — the latter lowercases to genserver, which does not exist), and the failure arrives as undef with no hint. The declaration names the BEAM atom exactly; the Kex-side spelling becomes free.
Typechecker seam
src/semantic/typechecker.cxx:3149-3162 is the whole change surface:
- found, arity matches — check arguments against the declared parameters, return the declared result type
- found, arity does not match — error naming the declared arity (the single highest-value diagnostic: an arity mistake on the BEAM is
undefat runtime with no source location) - not found — today's behaviour, unchanged
--check-extern wraps each declared foreign call in a shape assertion (is_binary, is_list, is_pid, tuple arity) on arguments and result, reporting mismatches against the declaration with its source location. Off by default.
using for foreign paths
src/semantic/resolve_pass.cxx:244must not warn for a path rooted atErlang/Elixir/Gleam— there is no source root to find it in, and that is not an error- The alias must reach
modulePathinsrc/ir/lower.cxx:2287, which already consultsmoduleAliasesfor user modules
using Erlang.Gen_server, as: GenServer
GenServer.call(pid, msg)
Walker
Report "a foreign call requires the BEAM backend — use -R or -c" at src/interpreter/evaluator.cxx:1926, which already has the namespace name in hand. A package whose public API bottoms out in extern is BEAM-only, and tey test on it must run under -R.
Declaration generation
tey extern gen <module-or-package>: read exports and specs from the compiled .beam (beam_lib:chunks/2 for Dbgi/Docs, or Code.Typespec.fetch_specs/1 for Elixir), map onto the vocabulary, emit ErlTerm with a # TODO for everything unmapped, write extern/<module>.kex with atom: filled in whenever the lowercasing rule would not reproduce the module name. Generated output is a starting point a human narrows — same relationship @types packages have with the JS they describe.
Hex dependencies
bundle "myapp" do
tey("greet", git: "https://github.com/kexhq/greet", tag: "~> 0.2")
hex("cowboy", "~> 2.12") # Erlang, built with erlc
hex("jason", "~> 1.4", build: "mix") # Elixir, needs a real build tool
end
Tey.Manifest.Dependencygains a source kind;Tey.Manifest.readdispatches on the leading word, so ahex(branch is a small change- Hex is a plain HTTP repository (
repo.hex.pmtarballs + protobuf version list);Tey.Semveralready parses Hex's constraint syntax Tey.Cachegains a parallel content-addressed key;CHECKSUMverified against the registry, hash recorded intey.lock— same guarantee the git path gets fromgit archive- Plain Erlang packages (
src/*.erl+.app.src, no plugins, noparse_transform, no NIFs) compile witherlcdirectly - Anything else requires an explicit
build: "rebar3"/build: "mix"— a per-dependency grant to execute the package's build definition; without the flag, a layouterlccannot handle is a hard error naming what it found kex --beam-path <dir>appends-pawhen-Rspawnserl;Tey.Commandspasses dependency beam paths alongside source roots
Sequencing
- Make bodiless signatures authoritative for calls — prerequisite and standalone bug fix (below)
extern module+ vocabulary + the typechecker seam — the arity check alone justifies the stepusingfor foreign paths + the walker diagnostictey extern gen— turns 1–2 into a feature that pays for itself against real OTP moduleshex(...), fetch, verify, lock — no building yeterlcbuilding +--beam-pathbuild: "rebar3"/build: "mix"— last, because it runs other people's code
Prerequisite (standalone bug)
Bodiless signatures are collected but do not drive checking — this passes -C clean and then fails at runtime with Undefined function: Foo.bar:
module Foo do
bar : Integer -> Integer
end
main do
IO.printLine(Foo.bar("nope")) # not reported
end
Non-goals
Sound typing of foreign calls; declared coercions between BEAM and Kex shapes; making the walker call foreign code; NIFs/port drivers; publishing Kex packages to Hex.
Activity