MEP-76 research bundle
This bundle is the informative companion to MEP-76. 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
| Note | Subject |
|---|---|
| 01. Language surface | The import ruby "..." import shape, the mochi.toml [ruby-dependencies] and [ruby] tables, the CLI surface (mochi pkg add ruby, mochi pkg publish --to=rubygems.org), and the per-import alias semantics. |
| 02. Design philosophy | Why a bidirectional bridge, why RBS over YARD as the primary type source, why a synthesised shim over direct FFI, why OIDC trusted publishing is the only publish path. |
| 03. Prior-art bridges | PyO3-pyo3-sys, JRuby FFI, TruffleRuby Polyglot, ruby-ffi, fiddle, Sorbet, RBS. What each gets right and what MEP-76 borrows. |
| 04. RBS bundled-sig ingest | Walking sig/**/*.rbs from the gem tarball, the RBS 3.x grammar subset the bridge parses, the Go-side RBS parser shape, and the rbs-source = "bundled" path. |
| 05. Type mapping | The closed translation table from RBS types to Mochi types, the SkipReport cases, the generic class handling, the nil / untyped desugar. |
| 06. RubyGems publish flow | The rubygems.org upload protocol, the gemspec metadata requirements, the .gem tarball shape, the publish-side gate. |
| 07. OIDC trusted publishing | The rubygems.org OIDC flow, the JWT claim requirements, the gem push provenance attestation, and the API key fallback transition path. |
| 08. Native C extension gems | Pre-built binary gem selection, the platform-suffix matching, pure-Ruby fallback gems, source build opt-in, and the SkipReport path when no option is available. |
| 09. Bundler and mochi.lock | Gemfile.lock format, the [[ruby-package]] mochi.lock schema, --check mode, version conflict resolution, and bundle install orchestration without a Gemfile in the user's source tree. |
| 10. Ractor and Fiber concurrency | Ruby 3.x Ractors, Fibers and the Fiber::Scheduler interface, the async gem opt-in, GVL implications, and TruffleRuby compatibility notes. |
| 11. Version resolution | RubyGems version operators, the compact index format, pre-release handling, platform-suffix selection, and the two-tier resolution strategy (Go resolver + Bundler PubGrub fallback). |
| 12. Risks and alternatives | The risk register (RBS coverage gaps, schema instability, native extension availability, Bundler drift, OIDC API stability, GVL assumption, Ruby version fragility) and rejected alternatives (YARD-only, runtime introspection, API key publish, Ractor-default, skip native extensions, delegate all resolution to Bundler). |
Cross-references
- MEP-76 spec — the normative document.
- MEP-56 — the Ruby transpiler this bridge builds on.
- MEP-57 — the source-level package system whose manifest and lockfile the bridge extends.
- Implementation tracking — the per-phase delivery status.