Skip to main content

MEP-66 research bundle

This bundle is the informative companion to MEP-66. It documents the design space the bridge sits in: prior art, the choices considered and rejected, the trade-offs accepted, and the open risks. The bundle is meant to be read alongside the spec, not in place of it.

Notes​

NoteSubject
01. Language surfaceThe import erlang "..." import shape, the mochi.toml [erlang-dependencies], [erlang], and [erlang.publish] tables, the CLI surface (mochi pkg add erlang, mochi pkg publish --to=hex.pm), and the per-import alias/sub-namespace resolution rule.
02. Design philosophyWhy a bidirectional bridge, why BEAM abstract code over Dialyzer PLT or EDoc XML, why OTP Port over NIF or C-node, why the ok/error idiom maps to result<T, string>, why OIDC trusted publishing is the only publish path.
03. Prior-art bridgesRustler (Rust→BEAM NIF), Zigler (Zig NIF), erlport (Python/Ruby via Ports), Ports vs C-nodes vs NIFs, Erlix, JInterface. What each gets right and what MEP-66 borrows.
04. BEAM typespec ingestThe Dbgi/Abst chunk format, the ETF encoding, the Go-side ETF parser shape, walking -spec and -type directives, the beam-ingest-sha256 reproducibility anchor, OTP 17 vs 20+ chunk differences.
05. Type mappingThe closed translation table from Dialyzer typespecs to Mochi types, the SkipReport cases, the ok/error idiom pattern recogniser, the atom() → string marshalling decision, the pid() and reference() opaque handle strategy.
06. Hex.pm publish flowThe Hex.pm HTTP API v2 upload protocol, the package tarball structure (outer + inner tar, three hashes), the .app.src metadata requirements, the publish-side gate, and the rebar3 hex publish integration path.
07. OIDC trusted publishingThe Hex.pm trusted publishing flow (2024), the JWT claim requirements, the GitHub Actions OIDC provider endpoint, the id-token: write permission, and the HEX_API_KEY fallback prohibition rationale.
08. OTP Port bridge protocolThe ETF packet framing ({packet, 4} mode), the call/response message schema, the gen_server wrapper shape, Port process lifecycle (start/stop/crash recovery), and the latency profile of Port round-trips vs NIF calls.
09. rebar3 and mochi.lockThe rebar3.lock format vs [[erlang-package]] in mochi.lock, the three-hash verification scheme (outer SHA-256, inner SHA-256, inner SHA-512), the --check mode gate, and the rebar.config synthesis pipeline.
10. OTP behavior bindingsgen_server call/cast/info patterns, supervisor start/stop/which_children, application start/stop, and how the bridge translates the stateful gen_server surface to Mochi's stateless extern fn model via opaque Pid handles.
11. Version resolutionHex.pm's version constraint operators (~>, >=, <, and), the Hex.pm HTTP API v2 compact index format, pre-release handling, the bridge's two-tier resolution (Go resolver + rebar3 fallback), and Elixir-compat package selection.
12. Risks and alternativesThe risk register (BEAM abstract code drift across OTP versions, EDoc coverage gaps, Port latency, rebar3 version fragility, Hex.pm API stability, ok/error pattern false positives, WASM exclusion) and rejected alternatives (NIF default, Dialyzer PLT primary, C-node bridge, HEX_API_KEY publish, full Elixir support, custom resolver).

Cross-references​