beni 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3b827b40a0385e917ba034d28ced80adccc7b0370d4779d1ed3fb2826307846
-  data.tar.gz: 398ad4b15f5158b20fef7bf228ec2868a486e141bcce14c201a403b65baa42f9
+  metadata.gz: c331de89e1d8d6996c41ba290800042b985d932ffc9c0ef0d957753144c195b0
+  data.tar.gz: 3d4e9478ee1b7d4e5fcd91f0f47b49d750e491b062580ad8be902ca68548b35b
 SHA512:
-  metadata.gz: ca47ed907af19136e59beabc0277cdc55850d57f6593b41b5d7086ebd7bb89d9506b07eacee92b9c617e9f99089dad1237b686affc70fd3a65e1e81d1c4e3e64
-  data.tar.gz: fca25b38eadd6f2c5087a736387ba85b232ac3332c1900ab3d313b24ba9e7f96a9f0a952c0d0a9ae494bb4e0da70e9d8bc98a47465b6a28ee368f1ff0fa56d79
+  metadata.gz: '093f8eeb0ab8d91e94c01a74808716d875c112d9d0351b31cb98d4db27891147f6b11cca04fc655e4f50f0bca90dbca3be1c81b907b4bacbdd4419ee58050f56'
+  data.tar.gz: 384eeb4227d265d66c4eaa4a35aab0a1988ad99af1fce770e73a0faf9c32d2a3e15444d4cea9f1b579064a430e57f2a9f26015ef1cf1583a0bd96ece6fdede41

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## 0.1.0 (2026-06-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* require Ruby >= 3.3
+* **beni-sys:** align bindgen with the archive via libmruby.flags.mak
+* **beni:** default the build to mruby's upstream config, not the repo's
+
+### Features
+
+* add Beni::Builder driving mruby's own rake ([2be29d3](https://github.com/elct9620/beni/commit/2be29d3d1fa353804413b92203758232796fad3b))
+* add Beni::Tasks exposing the beni:* rake namespace ([2833c23](https://github.com/elct9620/beni/commit/2833c23a7a01efea185cfcd165f4499e5ffc0cf7))
+* add RBS type checking and Claude Code quality hooks ([707e692](https://github.com/elct9620/beni/commit/707e6920f26b21ff4a67f8a31691fc21e1d5dd81))
+* **beni-sys:** align bindgen with the archive via libmruby.flags.mak ([8d019dc](https://github.com/elct9620/beni/commit/8d019dc40fb0c6f7cf5b4139ac27b6a3b7d1459a))
+* **beni:** compile the full wrapper API surface in placeholder mode ([00a429d](https://github.com/elct9620/beni/commit/00a429dfe524b7daaeb72765841136e2e92ed83a))
+* **beni:** generate self-contained build configs via rake beni:config ([51c04c2](https://github.com/elct9620/beni/commit/51c04c214a1cc5b2766b68a1e54937cf00a5a69d))
+* **beni:** register typed Rust functions with method! and seal the panic boundary ([b1706a2](https://github.com/elct9620/beni/commit/b1706a2aa2aa9c8550846ea2e4d139720ec1aa34))
+* **beni:** ship Ruby surfaces as Gem implementations ([37b6260](https://github.com/elct9620/beni/commit/37b6260b235b4510d145ce8dd933e2f62bf265d8))
+* **beni:** surface mruby rejections as Err through magnus-shaped handles ([ccd2809](https://github.com/elct9620/beni/commit/ccd280974700e3c3943e541c4bf72260eaad74be))
+* **config:** generate the build config from the staged upstream default ([5429c54](https://github.com/elct9620/beni/commit/5429c542ceb58456be8b529c1422d4efe18ded07))
+* **dsl:** add the declarative configuration vocabulary and resolution ([a8cbe48](https://github.com/elct9620/beni/commit/a8cbe483e7ea877ae59277056ffae6f282c5fe54))
+* port kobako's rake chain as the compile-verification harness ([a0e69f2](https://github.com/elct9620/beni/commit/a0e69f20609fb293b317f4ee206169dd3f543f37))
+* port the vendor pipeline into Beni::Vendor ([4387e6b](https://github.com/elct9620/beni/commit/4387e6be8432975ebf69cdcd2c35bd02d38060d4))
+* ship the mruby build configs with the gem ([88d79d4](https://github.com/elct9620/beni/commit/88d79d4bbc4f28c12a767ae078d8ea6775e0fdc3))
+* **sys:** make archive discovery env-driven with no vendor fallback ([389d608](https://github.com/elct9620/beni/commit/389d6088644559ac3f53505b4fe9bfcc5f25b298))
+* **tasks:** switch Beni::Tasks to the declarative DSL ([7eaf07f](https://github.com/elct9620/beni/commit/7eaf07f8f2b6b57f6cb93aa37edebe680ee0b7b9))
+* **test:** add default_host consumer-scenario harness ([9d7d6d3](https://github.com/elct9620/beni/commit/9d7d6d3b339bcda266643ce3535efeb9b720cf0d))
+* **test:** exercise the generate-config chain as a consumer scenario ([2df1490](https://github.com/elct9620/beni/commit/2df1490ee19b161d9d8fb171d69669c7016c8fdd))
+* **vendor:** stage the wasi toolchain file into the mruby tree ([e081b69](https://github.com/elct9620/beni/commit/e081b694dfbe45b35ac58e45eb22fd5fe2997447))
+* **vendor:** vendor built-in version-checksum pairs and inject selection into toolchains ([b3edf10](https://github.com/elct9620/beni/commit/b3edf103351814f8e67d7d2a3f4fbf5fff6ec223))
+
+
+### Bug Fixes
+
+* **beni:** gate Mrb's repr(transparent) on mruby_linked, not wasm32 ([7d8c949](https://github.com/elct9620/beni/commit/7d8c9499e1365e6bb2c6551d1e918738163db1cb))
+* **beni:** prefix the remaining runtime errors for CI log grepping ([ffd799a](https://github.com/elct9620/beni/commit/ffd799a67bcdc1ca9dbb92d106c14f333afe14b8))
+* **beni:** treat init-failed mruby states and missing configs as errors ([e4c0bf5](https://github.com/elct9620/beni/commit/e4c0bf5c406717c7129901a11d5fb2791b33bf3e))
+* **beni:** type mrb_get_args count out-params as mrb_int, not c_int ([b21ee22](https://github.com/elct9620/beni/commit/b21ee225577d6b2bba8176836e426e7e25611b93))
+* **gemspec:** give source_code_uri its own URL ([3d3da60](https://github.com/elct9620/beni/commit/3d3da6092d0c7f222558a822f3b7c5c1660d0ff0))
+* **gemspec:** ship only the consumer-facing files and link the changelog ([176f18a](https://github.com/elct9620/beni/commit/176f18a77fb01f18502a0e0b6c1b237470e0d0fc))
+* **release:** pin the first release to 0.1.0 and drop the dead lock updaters ([5bd6106](https://github.com/elct9620/beni/commit/5bd61065d61f3e00cfbd6918d7dd803f2e9e11b4))
+
+
+### Miscellaneous Chores
+
+* require Ruby >= 3.3 ([de636e8](https://github.com/elct9620/beni/commit/de636e87163474f84f19e7163f22c51a1ec9dc22))
+
+
+### Code Refactoring
+
+* **beni:** default the build to mruby's upstream config, not the repo's ([0cafae1](https://github.com/elct9620/beni/commit/0cafae18e17350c0cbbd5d0048c1131e450cd573))

data/README.md

@@ -1,20 +1,131 @@
 # Beni
 
-mruby toolchain monorepo — a Ruby gem that manages the mruby build chain and
-Rust crates that bind the mruby C API, extracted from the
-[kobako](https://github.com/elct9620/kobako) project.
-
-> **Status**: under active development. The published `0.0.0` versions reserve
-> the package names while the build chain and binding crates are extracted
-> from kobako; no usable API ships yet.
+beni gives Rust developers a magnus-like experience for mruby: a Ruby gem
+manages the mruby build chain, and Rust crates expose a safe, typed API over
+the resulting `libmruby.a`. Extracted from the
+[kobako](https://github.com/elct9620/kobako) project; APIs follow 0.x semver
+semantics and may still evolve between minor versions.
 
 ## Packages
 
+All three packages release in lockstep under a single version.
+
 | Package | Registry | Role |
 |---|---|---|
-| `beni` gem | rubygems.org | mruby dependency manager — vendors mruby source, builds `libmruby.a`, future mrbgem management |
+| `beni` gem | rubygems.org | Rake tasks + DSL config that download mruby and build `libmruby.a` |
 | `beni-sys` crate | crates.io | bindgen FFI surface over the mruby C API |
-| `beni` crate | crates.io | typed Rust wrapper over `beni-sys` (magnus analog) |
+| `beni` crate | crates.io | safe typed wrapper over `beni-sys`, aligned with magnus idioms |
+
+## Getting started
+
+### Build `libmruby.a` with the gem
+
+Add `beni` to your Gemfile and install the task library in your Rakefile:
+
+```ruby
+require "beni/tasks"
+
+Beni::Tasks.new
+```
+
+```bash
+rake beni:build
+```
+
+This downloads the pinned mruby release, builds it with mruby's untouched
+upstream default config, and stages `vendor/mruby/build/host/lib/` with
+`libmruby.a` and its `libmruby.flags.mak` compile-flags sidecar — everything
+the crates need.
+
+To tune the build, declare a config path and generate the seed:
+
+```ruby
+Beni::Tasks.new do
+  build_config "build_config/mruby.rb"
+end
+```
+
+`rake beni:config` writes a self-contained copy of the upstream default
+config to that path. The file is yours to edit — add targets, gems, or
+defines; beni never rewrites it.
+
+### Embed mruby from Rust
+
+Add the `beni` crate to your Cargo.toml, then point archive discovery at
+the vendor tree the gem staged:
+
+```bash
+BENI_VENDOR_DIR=$PWD/vendor cargo build
+```
+
+A crate ships its Ruby surface as a `Gem` and installs it during
+interpreter setup:
+
+```rust
+use beni::{method, Error, Gem, Module, Mrb, Value};
+
+fn answer(_mrb: &Mrb, _self: Value) -> i32 {
+    42
+}
+
+struct WidgetGem;
+
+impl Gem for WidgetGem {
+    fn init(mrb: &Mrb) -> Result<(), Error> {
+        let widget = mrb.define_class(c"Widget", mrb.object_class())?;
+        widget.define_method(mrb, c"answer", method!(answer, 0))?;
+        Ok(())
+    }
+}
+
+fn main() {
+    let mrb = Mrb::open().expect("mruby interpreter");
+    mrb.init_gem::<WidgetGem>().expect("Widget surface");
+    // Widget#answer now returns 42 to any Ruby code the interpreter runs.
+}
+```
+
+With no archive discovery variable set, a host build compiles in
+placeholder mode: `cargo check` passes, no FFI surface is exported, and
+`Mrb::open` returns an error — so `beni` is safe to take as a transitive
+dependency. Any C API the typed wrapper does not cover stays reachable
+through the unsafe `beni::sys` escape hatch.
+
+### Cross-compile for wasm32-wasip1
+
+Declare a `wasi` target referencing the `wasi-sdk` toolchain:
+
+```ruby
+Beni::Tasks.new do
+  build_config "build_config/mruby.rb"
+
+  target :host
+  target :wasi do
+    toolchain "wasi-sdk"
+  end
+end
+```
+
+and append the cross build to the generated config:
+
+```ruby
+MRuby::CrossBuild.new("wasi") do |conf|
+  conf.toolchain :wasi
+end
+```
+
+`conf.toolchain :wasi` resolves to the wasi toolchain file
+`beni:vendor:setup` stages into the mruby tree whenever `wasi-sdk` is
+selected — the cross-compile settings ship with beni and update with it.
+After `rake beni:build`, name the staged archive and the wasi-sdk root
+explicitly for the cargo side (a cross-compiled cargo target never reads
+the vendor tree on its own):
+
+```bash
+MRUBY_LIB_DIR=$PWD/vendor/mruby/build/wasi/lib \
+WASI_SDK_PATH=$PWD/vendor/wasi-sdk \
+cargo build --target wasm32-wasip1
+```
 
 ## Toolchain
 
@@ -28,12 +139,28 @@ are unaffected by the pairing.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then,
-run `rake test` to run the tests. You can also run `bin/console` for an
-interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies, then
+`bundle exec rake` for the default gate (tests + RuboCop + Steep). The repo
+dogfoods its own gem: the Rakefile wires `Beni::Tasks` with the validation
+config `build_config/mruby.rb` (host + wasi targets), and a repo-local rake
+chain verifies the crates compile against a real `libmruby.a` on both the
+host target and wasm32-wasip1:
+
+```bash
+bundle exec rake rust:verify   # beni:build + check/test (host) + check (wasm32)
+```
+
+Behavior contracts live in `SPEC.md` — the source of truth the
+implementation follows.
+
+## Releasing
 
-The Rust crates live under `crates/` in a Cargo workspace at the repo root;
-`cargo check --workspace` covers both.
+Releases are cut by release-please: merging the release PR tags the
+version and publishes the gem and both crates in lockstep through OIDC
+trusted publishing. One-time cleanup: after 0.1.0 ships, remove the
+`release-as` line (and the then-stale `last-release-sha`) from
+`release-please-config.json` — left in place it pins every subsequent
+release to 0.1.0.
 
 ## Contributing
 

data/lib/beni/build_config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Beni
+  # Generates the consumer's editable mruby build config: a verbatim
+  # copy of the staged mruby source's own +build_config/default.rb+ —
+  # the configured version's upstream default. Exposed as
+  # +rake beni:config+ by +Beni::Tasks+; the generated file belongs to
+  # the consuming project and seeds further customization.
+  module BuildConfig
+    module_function
+
+    # Copy the staged source's default config to +dest+, creating
+    # missing parent directories. Requires +version+'s mruby source
+    # staged under +mruby_dir+ and refuses to clobber an existing
+    # (likely hand-tuned) config. Returns +dest+.
+    def generate(dest, mruby_dir:, version:)
+      raise Error, "[beni] #{dest} already exists — delete it first to regenerate" if File.exist?(dest)
+
+      source = staged_default_config(mruby_dir, version)
+      FileUtils.mkdir_p(File.dirname(dest))
+      FileUtils.cp(source, dest)
+      dest
+    end
+
+    # The staged source's upstream default config path, verified to be
+    # +version+'s: the +.beni-version+ marker +Vendor::Tarball#prepare+
+    # stamps must match, so a stale tree never seeds a config for the
+    # wrong release.
+    def staged_default_config(mruby_dir, version)
+      source = File.join(mruby_dir, "build_config", "default.rb")
+      return source if staged_version(mruby_dir) == version && File.exist?(source)
+
+      raise Error,
+            "[beni] mruby #{version}'s source is not staged at #{mruby_dir} — " \
+            "run `rake beni:vendor:setup` first"
+    end
+
+    def staged_version(mruby_dir)
+      marker = File.join(mruby_dir, Vendor::Tarball::VERSION_MARKER)
+      File.read(marker).strip if File.exist?(marker)
+    end
+  end
+end

data/lib/beni/builder.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+
+module Beni
+  # Drives the vendored mruby tree's build to produce the per-target
+  # +libmruby.a+ archives, by running mruby's own +Rakefile+ — the
+  # documented build entry point (doc/guides/compile.md). With no
+  # +build_config+, mruby falls back to its own
+  # +build_config/default.rb+; an explicit config is wired in via the
+  # +MRUBY_CONFIG+ env var, which mruby resolves as an absolute path.
+  class Builder
+    # mruby's anonymous +MRuby::Build.new+ names its target "host"
+    # (lib/mruby/build.rb), so the upstream default config produces
+    # +build/host/lib/libmruby.a+. A custom build config with
+    # different target names supplies its own list via +Beni::Tasks+.
+    DEFAULT_TARGETS = %w[host].freeze
+
+    attr_reader :vendor_dir, :build_config, :targets
+
+    def initialize(vendor_dir:, build_config: nil, targets: DEFAULT_TARGETS)
+      @vendor_dir = vendor_dir
+      @build_config = build_config
+      @targets = targets
+    end
+
+    def mruby_dir
+      File.join(vendor_dir, "mruby")
+    end
+
+    def libmruby_path(target)
+      File.join(mruby_dir, "build", target, "lib", "libmruby.a")
+    end
+
+    def libmruby_paths
+      targets.map { |target| libmruby_path(target) }
+    end
+
+    # True when every target's artifacts — +libmruby.a+ plus the
+    # +libmruby.flags.mak+ sidecar +beni-sys+ parses for ABI alignment
+    # — are already present, letting callers skip the build without
+    # spawning a subprocess. An archive without its sidecar (e.g. a
+    # tree built before flags.mak joined the contract) triggers a
+    # rebuild, which is incremental and only emits the missing file.
+    def built?
+      artifact_paths.all? { |path| File.exist?(path) }
+    end
+
+    # Idempotent build entry point for +rake beni:build+: skip with a
+    # note when every artifact is already present, otherwise build and
+    # report readiness. A declared config that does not exist aborts
+    # before the skip check — stale artifacts must not mask it.
+    def ensure_built
+      check_build_config!
+      if built?
+        puts "[beni] libmruby.a already present for #{targets.join(" + ")} — skipping"
+        return
+      end
+
+      build
+      puts "[beni] libmruby.a ready for #{targets.join(" + ")}"
+    end
+
+    # Run mruby's rake and raise unless every target's +libmruby.a+
+    # exists afterwards. Alongside the default task, each target's
+    # +libmruby.flags.mak+ file task is requested explicitly — mruby's
+    # embedder interface recording the exact compile flags, which
+    # +beni-sys+'s build script parses to keep bindgen's view of the
+    # ABI aligned with the archive. (The file task is defined per
+    # target but not part of mruby's default products.) The underlying
+    # build is make-style incremental, so re-running on a partially
+    # built tree only compiles what is missing.
+    def build
+      check_build_config!
+      cmd = [RbConfig.ruby, "-S", "rake", "default", *flags_mak_paths]
+      puts "[beni] cd #{mruby_dir} && #{env.map { |k, v| "#{k}=#{v}" }.join(" ")} #{cmd.join(" ")}"
+      run_mruby_rake(env, cmd)
+      verify_artifacts!
+    end
+
+    # Remove each target's build tree (keeps the vendored mruby source).
+    def clean
+      targets.each do |target|
+        dir = File.join(mruby_dir, "build", target)
+        FileUtils.rm_rf(dir)
+        puts "[beni] removed #{dir}"
+      end
+    end
+
+    private
+
+    # Every artifact the build must leave behind: the per-target
+    # archive and its flags.mak sidecar.
+    def artifact_paths
+      libmruby_paths + flags_mak_paths
+    end
+
+    # Spawn mruby's rake with the parent environment plus the +env+
+    # overlay. Extracted as a seam so tests can fake the subprocess
+    # while observing the full env + cmd contract.
+    def run_mruby_rake(env, cmd)
+      system(env, *cmd, chdir: mruby_dir, exception: true)
+    end
+
+    # Environment for the mruby build subprocess. +BENI_VENDOR_DIR+
+    # lets build configs resolve the vendor tree without knowing where
+    # the consuming project lives on disk. +MRUBY_CONFIG+ is only set
+    # for an explicit config — absent, mruby falls back to its own
+    # +build_config/default.rb+ (lib/mruby/build.rb#mruby_config_path).
+    def env
+      env = { "BENI_VENDOR_DIR" => vendor_dir }
+      env["MRUBY_CONFIG"] = build_config if build_config
+      env
+    end
+
+    # Per-target +libmruby.flags.mak+ file-task paths, matching the
+    # task names mruby defines in tasks/libmruby.rake (absolute,
+    # anchored on the default +build/<target>+ layout).
+    def flags_mak_paths
+      targets.map { |target| File.join(mruby_dir, "build", target, "lib", "libmruby.flags.mak") }
+    end
+
+    # The declared config belongs to the consumer; a path that does
+    # not exist is a configuration error named before anything spawns.
+    def check_build_config!
+      return if build_config.nil? || File.exist?(build_config)
+
+      raise Error, "[beni] build config #{build_config} does not exist"
+    end
+
+    # Report every missing artifact at once, so a multi-target build
+    # failure shows the whole gap instead of one path per run.
+    def verify_artifacts!
+      missing = artifact_paths.reject { |path| File.exist?(path) }
+      return if missing.empty?
+
+      raise Error, "[beni] build completed but artifacts are missing:\n  #{missing.join("\n  ")}"
+    end
+  end
+end

data/lib/beni/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Beni
+  # Resolution output of the Tasks DSL — immutable, defaults applied.
+  # The only input the task-definition phase reads: +vendor_dir+ fully
+  # resolved (declaration > +BENI_VENDOR_DIR+ > +vendor/+), +build_config+
+  # as an absolute path or +nil+ for mruby's untouched upstream default,
+  # +targets+ as the declared set (or +["host"]+), and +toolchains+ as
+  # the reference-driven selection.
+  class Configuration < Data.define(:vendor_dir, :build_config, :targets, :toolchains)
+  end
+end

data/lib/beni/dsl/context.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Beni
+  module DSL
+    # Top-level vocabulary of the +Beni::Tasks.new+ block. Collects the
+    # scalar settings, target declarations, and toolchain definitions —
+    # validating each declaration eagerly — and resolves them into the
+    # +Configuration+ the task-definition phase consumes.
+    class Context
+      def initialize
+        @settings = {}
+        @targets = {}
+        @definitions = {}
+      end
+
+      def version(value)
+        declare_scalar(:version, value)
+      end
+
+      def build_config(path)
+        declare_scalar(:build_config, path)
+      end
+
+      def vendor_dir(path)
+        declare_scalar(:vendor_dir, path)
+      end
+
+      # A +target <name>+ declaration; the optional block holds the
+      # target's toolchain references.
+      def target(name, &block)
+        key = name.to_s
+        raise Error, "duplicate `target` declaration #{key.inspect}" if @targets.key?(key)
+
+        # @type var references: Array[String]
+        references = block ? TargetContext.collect(&block) : []
+        @targets[key] = Target.new(name: key, references: references)
+      end
+
+      # A top-level +toolchain <name>+ — always a definition, so the
+      # block is part of the grammar and +mruby+ is never definable.
+      def toolchain(name, &block)
+        raise Error, "top-level `toolchain #{name.inspect}` must carry a definition block" unless block
+        if name == "mruby"
+          raise Error, "a toolchain definition never names \"mruby\" — select it with the `version` setting"
+        end
+
+        DSL.assert_known_toolchain!(name)
+        raise Error, "duplicate toolchain definition #{name.inspect}" if @definitions.key?(name)
+
+        @definitions[name] = DefinitionContext.collect(name, &block)
+      end
+
+      # Resolve the collected declarations (SPEC.md Behaviors: selection
+      # is reference-driven; defaults fall to the built-in pairs).
+      def configuration
+        Configuration.new(
+          vendor_dir: resolved_vendor_dir,
+          build_config: resolved_build_config,
+          targets: resolved_targets,
+          toolchains: selected_names.map { |name| selected_toolchain(name) }
+        )
+      end
+
+      private
+
+      def declare_scalar(key, value)
+        raise Error, "duplicate `#{key}` declaration" if @settings.key?(key)
+
+        @settings[key] = value
+      end
+
+      def resolved_vendor_dir
+        File.expand_path(@settings[:vendor_dir] || ENV.fetch("BENI_VENDOR_DIR", nil) || "vendor")
+      end
+
+      def resolved_build_config
+        path = @settings[:build_config]
+        path && File.expand_path(path)
+      end
+
+      def resolved_targets
+        return Builder::DEFAULT_TARGETS.dup if @targets.empty?
+
+        @targets.keys
+      end
+
+      # References plus their transitive dependencies; +mruby+ is always
+      # selected and leads the set so it stages first.
+      def selected_names
+        references = @targets.values.flat_map(&:references)
+        dependencies = references.flat_map { |name| Vendor::DEPENDENCIES.fetch(name, []) }
+        (%w[mruby] + references + dependencies).uniq
+      end
+
+      def selected_toolchain(name)
+        definition = @definitions[name]
+        return SelectedToolchain.new(name: name, version: definition.version, sha256: definition.sha256) if definition
+
+        version = name == "mruby" ? mruby_version : Vendor::BUILT_IN_PAIRS.fetch(name).fetch(:version)
+        SelectedToolchain.new(name: name, version: version, sha256: Vendor.built_in_sha256(name, version))
+      end
+
+      def mruby_version
+        @settings[:version] || Vendor::BUILT_IN_PAIRS.fetch("mruby").fetch(:version)
+      end
+    end
+  end
+end

data/lib/beni/dsl/definition_context.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Beni
+  module DSL
+    # Vocabulary inside a top-level +toolchain <name> do … end+ block —
+    # the +(version, sha256)+ pair and nothing else. Both fields are
+    # required exactly once; the check runs when the block returns.
+    class DefinitionContext
+      # Run +block+ on a fresh context and return the collected
+      # ToolchainDefinition.
+      def self.collect(name, &)
+        context = new(name)
+        context.instance_exec(&)
+        context.to_definition
+      end
+
+      def initialize(name)
+        @name = name
+        @version = nil
+        @sha256 = nil
+      end
+
+      def version(value)
+        raise Error, "duplicate `version` in toolchain #{@name.inspect} definition" if @version
+
+        @version = value
+      end
+
+      def sha256(value)
+        raise Error, "duplicate `sha256` in toolchain #{@name.inspect} definition" if @sha256
+
+        @sha256 = value
+      end
+
+      # The collected definition; raises when the block left +version+
+      # or +sha256+ undeclared.
+      def to_definition
+        version = @version
+        sha256 = @sha256
+        if version.nil? || sha256.nil?
+          missing = [("version" if version.nil?), ("sha256" if sha256.nil?)].compact
+          raise Error, "toolchain #{@name.inspect} definition missing #{missing.join(" and ")}"
+        end
+
+        ToolchainDefinition.new(name: @name, version: version, sha256: sha256)
+      end
+    end
+  end
+end

data/lib/beni/dsl/target_context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Beni
+  module DSL
+    # Vocabulary inside a +target <name> do … end+ block — block-less
+    # toolchain references only. References are set-semantic: repeats
+    # collapse, and referencing +mruby+ is legal redundancy.
+    class TargetContext
+      # Run +block+ on a fresh context and return the collected
+      # reference names.
+      def self.collect(&)
+        context = new
+        context.instance_exec(&)
+        context.references
+      end
+
+      attr_reader :references
+
+      def initialize
+        @references = []
+      end
+
+      def toolchain(name, &block)
+        if block
+          raise Error,
+                "`toolchain #{name.inspect}` inside a target block must not carry a block — " \
+                "definitions live at the top level"
+        end
+        DSL.assert_known_toolchain!(name)
+
+        @references << name unless @references.include?(name)
+      end
+    end
+  end
+end

data/lib/beni/dsl.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Beni
+  # Declarative configuration vocabulary for +Beni::Tasks+. Three
+  # contexts each expose exactly the declarations legal at their
+  # position — top level (+Context+), inside a target block
+  # (+TargetContext+), and inside a toolchain definition block
+  # (+DefinitionContext+) — so a malformed declaration fails in the
+  # method itself, at definition time.
+  module DSL
+    module_function
+
+    # A toolchain name outside the Vendor registry fails at the
+    # declaration that names it, never mid-build.
+    def assert_known_toolchain!(name)
+      return if Vendor::TOOLCHAIN_FACTORIES.key?(name)
+
+      raise Error, "unknown toolchain #{name.inspect} (known: #{Vendor::TOOLCHAIN_FACTORIES.keys.join(", ")})"
+    end
+  end
+end
+
+require_relative "dsl/context"
+require_relative "dsl/target_context"
+require_relative "dsl/definition_context"

data/lib/beni/selected_toolchain.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Beni
+  # One selected toolchain with its resolved +(version, sha256)+ pair.
+  # +sha256+ is concrete at resolution time — a definition's declared
+  # value or the built-in checksum +Beni::Vendor+ resolves. +nil+ has
+  # exactly one reachable meaning: mruby at a non-default version, where
+  # verification falls to the TOFU sidecar path.
+  class SelectedToolchain < Data.define(:name, :version, :sha256)
+  end
+end