ace-lab 0.13.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff20c0d594202a649d5597257411b611d6faf6b66128fd8ff4ad0702989b6e16
-  data.tar.gz: 1d6575916e526eec678ee39c9be5025f53653fcdfac27c8075692c936d3351bd
+  metadata.gz: 347fa4748ebbcf945253d67f0e9f2f7de3cfd88a11abf134cf2aaf40128c9054
+  data.tar.gz: 934f7b130e93180ab259a0ec4efa2598980af7ce3935628bf9e295e8b4689451
 SHA512:
-  metadata.gz: 32b6ee73258e1534a9ff91f2bc83d30ff4265b124aefcee056652dd0544ef770aba4036e055e282fc35ea1c2a993cfefa67f46480e82ecf4f294fbda5561deeb
-  data.tar.gz: 786a3ca1af5fad657f722d3ea2c0ba525988c5461ed18a94023650e17f5b7870c15a754d71560ee442e78bd6527a42823d25dc297911666156bf57287072e9c7
+  metadata.gz: 1def278779e6c0593732ebb7872e0ee05aeaed5bacff5c6d623d13a15a1edea755cfe7bb6506edd11d2b22f8c71d8d64c3870bf9b35207395622f2f9c8ccd781
+  data.tar.gz: 0b459c559a716459349d6b7b96ff3dfb521413c526593549e06a18d48a1b682d0d1e006e783ffa80eea9409dabf639341e8556dcf17dcd40fc2baec3c7da9259

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-10-26
+
+### Added
+
+- Gem-set installation into the target lab runtime (gad.2 acceptance
+  gap #1, owner spec 8xg.t.sbz.7, L8 install group): the trusted
+  install manifest (still schema v1) gains an optional `gemset` section
+  — a sibling of `tools` — declaring the target runtime (`gem_home`,
+  an absolute path converged as GEM_HOME and GEM_PATH) and the required
+  gem set (`name` + exact `version`; unique names, versions validated
+  as real Gem versions, so ranges and "latest" are rejected at load).
+  A manifest without the section behaves exactly as before.
+  `ace-lab prepare` (and therefore `ace-lab install`) converges the gem
+  set into the declared runtime idempotently through a new
+  `GemsetProvisioner` molecule: exact version present = no-op
+  (`exists`), missing = installed, different version present = updated
+  (the declared version installed; RubyGems keeps versions side by
+  side and verify judges the declared set). The gem subprocesses run
+  with `GEM_HOME`/`GEM_PATH` pinned to the runtime through the same
+  argv runner seam as every other prepare step — with the invoking
+  process's bundler context stripped (`RUBYOPT`, `RUBYLIB`,
+  `BUNDLE_*`/`BUNDLER_*`), so `bundle exec ace-lab prepare` converges
+  the LAB runtime instead of its own bundle. The runtime directory is
+  created only with administrator privileges (the AccountProvisioner
+  seam); a symlink or non-directory runtime is refused (the
+  DirectoryProvisioner takeover posture); runtime failures fail every
+  gem item as a dependency and gate the install's projects and grants
+  like any other machine-level failure. `--dry-run` predicts
+  `would_install`/`would_update`/`exists` read-only and predicts the
+  wet privilege failure. The install report echoes the declared gemset
+  under `gemset`. `ace-lab verify` gained a matching read-only `gems`
+  check — every declared gem must be installed at its exact version in
+  the declared runtime, judged through the SAME probe the provisioner
+  converges from (a missing `gem` executable reports `unknown`, the
+  offline posture). `project add` stays project-scoped: gem
+  installation is machine-level provisioning and is deliberately not
+  added there. (PR #77)
+
 
 ## [0.13.0] - 2026-10-20
 

data/docs/usage.md

@@ -170,14 +170,23 @@ projects:                    # optional (consumed by ace-lab install)
 grants:                      # optional: trusted-tier principal grants
   ace-overseer:              # principal → declared project ids
     - atlas
+gemset:                      # optional (gad.2): target runtime + required gem set
+  gem_home: /opt/lab/gems    # absolute; converged as GEM_HOME and GEM_PATH
+  gems:                      # exact versions, unique names
+    - name: ace-lab
+      version: 0.13.0        # must be an exact gem version (no ranges)
 ```
 
 Statuses: accounts `created|exists|would_create|failed`; directories
 `created|exists|mode_fixed|would_create|would_fix_mode|failed`; keys
 `created|exists|would_create|would_repair_public|would_fix_mode|failed`
-(with the public `fingerprint`); roles `verified|failed`. `ok` in the
+(with the public `fingerprint`); roles `verified|failed`; gems
+`installed|updated|exists|would_install|would_update|failed` (one item
+per declared gem). `ok` in the
 JSON report means zero failed items. Key/role items whose account
-failed are reported as dependency failures instead of being attempted.
+failed are reported as dependency failures instead of being attempted;
+gem items fail as dependencies when the declared runtime did not
+prepare.
 
 `--dry-run` is a faithful prediction of the wet run (`would_*`
 statuses, zero mutations): keys and roles of an account the account
@@ -299,6 +308,26 @@ Behavior and guarantees:
   group, or other. A readable file behind an unsearchable directory
   (e.g. 0644 inside a 0700 directory owned by someone else) is
   `failed`, not `verified`. ACLs remain out of scope.
+- **Gem-set convergence (gad.2).** When the manifest declares a
+  `gemset`, prepare converges the declared gem set into the declared
+  target runtime (`gem_home`): a gem whose exact declared version is
+  already present is a no-op (`exists`), a missing gem is installed
+  (`installed`), a gem present at a different version is updated (the
+  declared version is installed; RubyGems keeps versions side by side
+  and verify judges the declared set). The `gem` subprocesses run with
+  `GEM_HOME`/`GEM_PATH` pinned to the runtime (through the POSIX `env`
+  command, argv arrays only) and with the invoking process's bundler
+  context stripped (`RUBYOPT`, `RUBYLIB`, `BUNDLE_*`/`BUNDLER_*`), so
+  a `bundle exec ace-lab prepare` converges the LAB runtime, never its
+  own bundle. The runtime directory is created only with
+  administrator privileges; a symlink or non-directory at `gem_home`
+  is refused (takeover posture). Installs fetch from the `gem`
+  command's configured sources (provisioning network access, like
+  cloning a declared remote) with `--no-document`. `--dry-run` is a
+  faithful prediction: the read-only probe runs, statuses are
+  `would_install`/`would_update`/`exists`, nothing is created or
+  installed, and a runtime that would need privileges predicts the wet
+  failure.
 - **Exit codes.** A wet run with failed items prints the report, then
   exits non-zero enumerating each `<section>/<item>: <message>`;
   `--dry-run` exits 0 whenever a report renders (conflicts appear as
@@ -408,8 +437,9 @@ existing molecules in a fixed order:
    present) must not grant projects the manifest does not declare: a
    ready or foreign lab is refused with a classified error and zero
    writes, identically in wet runs and `--dry-run` (prediction parity).
-2. **prepare (L8.1)** — accounts → directories → keys → roles, exactly
-   as `ace-lab prepare` (same organism, same per-item report).
+2. **prepare (L8.1)** — accounts → directories → keys → roles → gems,
+   exactly as `ace-lab prepare` (same organism, same per-item report;
+   the declared gem set converges into the declared target runtime).
 3. **project add (L8.2) per declared project** — repository, private
    `_overseer`, project registry, exactly as `ace-lab project add`.
    Projects are isolated: one failing project does not block the
@@ -486,6 +516,7 @@ never taken over, never cleaned:
 | --- | --- | --- |
 | declared directory | symlink, non-directory, or foreign ownership | step fails with a resolve-manually message; projects and grants are gated as dependency failures |
 | key pair | foreign-owned key files or `.ssh`, non-regular file | step fails with a resolve-manually message |
+| gem set | symlinked or non-directory runtime, missing privileges, or a failed probe/install | every gem item fails with a classified message; projects and grants are gated as dependency failures |
 | project repository | non-empty non-Git directory, or a Git repository with a different origin | step fails: "refusing to take over a foreign location" / "refusing to overwrite an existing registration"; the other projects still run (isolation) |
 | grants | trusted document granting projects outside the manifest, or a document that fails verification/parsing | the whole install refuses before any mutation ("refusing to install over a foreign lab"), wet and in `--dry-run` alike |
 
@@ -533,6 +564,9 @@ a concrete reason (never a bare boolean):
 | grants | the trusted document is present and verifiable, and every manifest principal's grants resolve through the real read-side mechanics (`CallerAuthorizer`) to the declared projects |
 | registry | each project is registered in its `.ace/lab/config.yml` (visibility through the configuration cascade) |
 | overseer | `.ace-tasks/_overseer/` exists and is ignored by Git (`git check-ignore`) |
+| adapters | configuration is a mapping; a declared local command resolves (probed for the target executors); `kind: hitl` routes are installed in every project's `.ace/hitl/config.yml` and satisfy the runtime loader's rules |
+| tools | each required tool resolves to an executable the target executors can run (presence + permission probe, no execution) |
+| gems | each declared gem is installed at its EXACT declared version in the declared target runtime — judged through the same read-only probe prepare converges from; a missing runtime, a missing gem or a version mismatch blocks readiness (a missing `gem` executable reports `unknown`, the offline posture) |
 
 The overall verdict is `ready` only when no check failed. A failure
 never hides healthy data: the full report renders first (table or

data/lib/ace/lab/atoms/install_schema.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rubygems/version"
+
 module Ace
   module Lab
     module Atoms
@@ -13,7 +15,7 @@ module Ace
         SCHEMA_VERSION = 1
         TOP_LEVEL_KEYS =
           %w[schema_version machine accounts directories keys roles projects grants
-             adapters tools].freeze
+             adapters tools gemset].freeze
         ENTRY_KEYS = {
           "accounts" => %w[username role create home],
           "directories" => %w[path owner mode],
@@ -29,6 +31,9 @@ module Ace
         DEFAULT_MODE = "0755"
         DEFAULT_KEY_TYPE = "ed25519"
         KEY_TYPES = [DEFAULT_KEY_TYPE].freeze
+        GEMSET_KEYS = %w[gem_home gems].freeze
+        GEM_KEYS = %w[name version].freeze
+        GEM_NAME_PATTERN = /\A[A-Za-z0-9._-]+\z/
 
         class << self
           # @param document [Object] parsed YAML document
@@ -71,7 +76,8 @@ module Ace
               "projects" => projects,
               "grants" => normalize_grants(document["grants"], projects.map { |p| p["id"] }),
               "adapters" => normalize_adapters(document["adapters"]),
-              "tools" => normalize_tools(document["tools"])
+              "tools" => normalize_tools(document["tools"]),
+              "gemset" => normalize_gemset(document["gemset"])
             }
           end
 
@@ -317,6 +323,71 @@ module Ace
             tools.map(&:strip).uniq
           end
 
+          # Target lab runtime and required gem set (gad.2 gap #1, owner
+          # spec 8xg.t.sbz.7): a sibling of `tools` declaring WHERE the
+          # lab's gems must live (`gem_home`, converged as GEM_HOME/
+          # GEM_PATH) and WHICH gems at WHICH exact versions. Absent =
+          # no runtime declared, behavior unchanged. Names must be real
+          # gem names; versions must parse as exact Gem versions (the
+          # same parser the runtime uses) — ranges and bare names are
+          # rejected so convergence is always exact-version.
+          def normalize_gemset(raw)
+            return {"gem_home" => nil, "gems" => []} if raw.nil?
+            unless raw.is_a?(Hash)
+              raise_invalid "gemset must be a mapping"
+            end
+
+            unknown = raw.keys - GEMSET_KEYS
+            unless unknown.empty?
+              raise_invalid "gemset has unknown key '#{unknown.sort.first}'"
+            end
+
+            gem_home = raw["gem_home"]
+            unless gem_home.is_a?(String) && !gem_home.strip.empty? && absolute_path?(gem_home.strip)
+              raise_invalid "gemset gem_home is required and must be an absolute path"
+            end
+
+            {"gem_home" => gem_home.strip, "gems" => normalize_gems(raw["gems"])}
+          end
+
+          def normalize_gems(raw)
+            gems = raw.nil? ? [] : raw
+            unless gems.is_a?(Array)
+              raise_invalid "gemset gems must be a list"
+            end
+            gems.each_with_index do |entry, index|
+              unless entry.is_a?(Hash)
+                raise_invalid "gemset gems entry ##{index} must be a mapping"
+              end
+              unknown = entry.keys - GEM_KEYS
+              unless unknown.empty?
+                raise_invalid "gemset gems entry ##{index} has unknown key '#{unknown.sort.first}'"
+              end
+            end
+
+            gems.map do |entry|
+              name = entry["name"]
+              unless name.is_a?(String) && name.strip =~ GEM_NAME_PATTERN
+                raise_invalid_entry("gemset gems", "name is required and must be a gem name")
+              end
+              version = entry["version"]
+              unless version.is_a?(String) && !version.strip.empty?
+                raise_invalid_entry("gemset gems", "version is required and must be an exact version")
+              end
+              begin
+                Gem::Version.new(version.strip)
+              rescue ArgumentError
+                raise_invalid_entry("gemset gems", "version must be an exact gem version")
+              end
+
+              {"name" => name.strip, "version" => version.strip}
+            end.tap do |gems|
+              duplicates_of(gems.map { |gem| gem["name"] }) do |_name|
+                raise_invalid_entry("gemset gems", "name is declared more than once")
+              end
+            end
+          end
+
           def optional_string(entry, section_name, field)
             value = entry[field]
             if !value.nil? && (!value.is_a?(String) || value.strip.empty?)

data/lib/ace/lab/cli/commands/prepare.rb

@@ -18,14 +18,16 @@ module Ace
             "accounts" => ->(item) { item["username"] },
             "directories" => ->(item) { item["path"] },
             "keys" => ->(item) { "#{item['account']}:#{item['path']}" },
-            "roles" => ->(item) { item["id"] }
+            "roles" => ->(item) { item["id"] },
+            "gems" => ->(item) { "#{item['name']} #{item['version']}" }
           }.freeze
 
           # "SHA256:" plus the first 20 base64 characters is enough to
           # eyeball-match a key without ballooning the table row.
           FINGERPRINT_WIDTH = 27
 
-          desc "Prepare accounts, directories, permissions, keys and roles from the trusted install manifest"
+          desc "Prepare accounts, directories, permissions, keys, roles and the declared " \
+            "gem set from the trusted install manifest"
 
           example [
             "--dry-run            # Predict all sections without mutating",

data/lib/ace/lab/cli/commands/verify.rb

@@ -16,13 +16,13 @@ module Ace
             "accounts" => "account", "directories" => "directory", "keys" => "account",
             "roles" => "id", "repositories" => "project", "grants" => "principal",
             "registry" => "project", "overseer" => "project",
-            "adapters" => "adapter", "tools" => "tool"
+            "adapters" => "adapter", "tools" => "tool", "gems" => "gem"
           }.freeze
 
           desc "Verify the installed lab's readiness under the target accounts (read-only): " \
             "accounts, directories, key pairs, role instructions, repository origins and " \
             "target-executor access, grant-based project visibility, private _overseer " \
-            "folders, configured communication/HITL adapters, required tools"
+            "folders, configured communication/HITL adapters, required tools, declared gem set"
 
           example [
             "--format json        # Machine-readable report for the overseer / next tool",

data/lib/ace/lab/molecules/gemset_provisioner.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "open3"
+require "fileutils"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently converges the install manifest's declared gem set
+      # into the declared target runtime (GEM_HOME; gad.2 gap #1, owner
+      # spec 8xg.t.sbz.7): a gem whose exact declared version is already
+      # present is a no-op (`exists`), a missing gem is installed
+      # (`installed`), a gem present at a different version is updated
+      # (the declared version installed alongside — RubyGems keeps
+      # versions side by side; verify judges the declared set). Probes
+      # and installs run the `gem` executable with GEM_HOME/GEM_PATH
+      # pinned to the target runtime through the SAME argv runner seam
+      # the other prepare molecules use (POSIX `env`, never a shell
+      # string, ADR-031) — so the lab runtime stays isolated from the
+      # installer's own gems and the runner stays injectable for
+      # dry-run and tests. The runtime directory itself is created only
+      # with administrator privileges (the same seam
+      # AccountProvisioner gates creation with) and a symlink or
+      # non-directory at the declared path is refused (the
+      # DirectoryProvisioner takeover posture). Every failure is a
+      # classified per-gem item with an actionable message; command
+      # failures surface only the exit status and the first stderr line.
+      class GemsetProvisioner
+        attr_reader :runner, :privileged, :dry_run
+
+        def initialize(runner: nil, privileged: nil, dry_run: false)
+          @runner = runner || method(:run_argv)
+          @privileged = privileged || -> { Process.euid.zero? }
+          @dry_run = dry_run
+        end
+
+        # @param runtime [Hash] normalized manifest gemset section
+        #   ({"gem_home" => path, "gems" => [{"name" =>, "version" =>}]})
+        # @return [Array<Hash>] one report per declared gem:
+        #   {name:, version:, gem_home:, status:, message:}
+        def call(runtime:)
+          gems = runtime["gems"]
+          return [] if gems.empty?
+
+          gem_home = runtime["gem_home"]
+          runtime_failure = ensure_runtime(gem_home)
+          gems.map do |gem|
+            if runtime_failure
+              base(gem, gem_home).merge("status" => "failed", "message" => runtime_failure)
+            else
+              converge(base(gem, gem_home), gem, gem_home)
+            end
+          end
+        end
+
+        # Public READ-ONLY probe (L8.5): the local versions of `name`
+        # inside the target runtime — the exact probe convergence runs,
+        # exposed so the readiness verifier reuses the same logic
+        # instead of reimplementing it (the two can never drift).
+        # @param name [String] gem name
+        # @param gem_home [String] target runtime (GEM_HOME)
+        # @return [Array(Symbol, Object)] [:ok, versions],
+        #   [:unknown, message] (no `gem` executable — offline posture)
+        #   or [:failed, message]
+        def runtime_versions(name:, gem_home:)
+          result = @runner.call(runtime_argv(gem_home,
+            ["gem", "list", name, "--exact", "--local"]))
+          return [:unknown, "gem not found in PATH; install RubyGems and rerun ace-lab prepare"] if result["status"] == "enoent"
+          return [:failed, command_failure("gem list", result)] unless result["status"] == "ok"
+
+          versions = parse_versions(result["out"], name)
+          if versions.nil?
+            return [:failed, "could not determine installed versions of gem '#{name}' from " \
+              "'gem list' output; rerun ace-lab prepare"]
+          end
+
+          [:ok, versions]
+        end
+
+        private
+
+        def base(gem, gem_home)
+          {"name" => gem["name"], "version" => gem["version"], "gem_home" => gem_home}
+        end
+
+        # One runtime failure fails every declared gem as a dependency
+        # (the keys-need-accounts posture): convergence is never
+        # attempted against a runtime that did not prepare.
+        def ensure_runtime(gem_home)
+          stat = lstat(gem_home)
+          return "gem runtime '#{gem_home}' is a symbolic link; refusing" if stat&.symlink?
+          return "gem runtime '#{gem_home}' exists but is not a directory; refusing" if stat && !stat.directory?
+          return nil if stat
+
+          unless @privileged.call
+            return "creating gem runtime '#{gem_home}' requires administrator privileges; " \
+              "rerun ace-lab prepare with sudo or create the directory manually"
+          end
+          return nil if @dry_run # prediction: creation would succeed
+
+          FileUtils.mkdir_p(gem_home)
+          nil
+        rescue Errno::EPERM, Errno::EACCES
+          "insufficient permissions while preparing gem runtime '#{gem_home}'; " \
+            "rerun ace-lab prepare with sudo or adjust ownership manually"
+        rescue SystemCallError => e
+          "gem runtime '#{gem_home}' could not be created (#{e.class.name}); rerun ace-lab prepare"
+        end
+
+        def converge(base, gem, gem_home)
+          kind, versions_or_message = runtime_versions(name: gem["name"], gem_home: gem_home)
+          # Prepare's fail-closed posture: an unprobeable runtime (no
+          # `gem` executable — the :unknown probe kind) fails the item in
+          # wet AND dry runs, exactly as the wet run would fail; verify
+          # maps the same probe kind to its offline `unknown` posture.
+          return base.merge("status" => "failed", "message" => versions_or_message) if kind != :ok
+
+          versions = versions_or_message
+          return base.merge("status" => "exists", "message" => nil) if versions.include?(gem["version"])
+
+          status = versions.empty? ? "install" : "update"
+          return base.merge("status" => "would_#{status}", "message" => nil) if @dry_run
+
+          failure = install(gem, gem_home)
+          return base.merge("status" => "failed", "message" => failure) if failure
+
+          if status == "install"
+            base.merge("status" => "installed", "message" => nil)
+          else
+            base.merge("status" => "updated", "message" => nil)
+          end
+        end
+
+        # Installs the EXACT declared version into the runtime. Sources
+        # are the gem command's own defaults — fetching from the
+        # configured gem source is provisioning network access, the same
+        # envelope as cloning a declared repository remote.
+        # @return [String, nil] the classified failure, nil on success
+        def install(gem, gem_home)
+          result = @runner.call(runtime_argv(gem_home,
+            ["gem", "install", gem["name"], "--version", gem["version"], "--no-document"]))
+          return nil if result["status"] == "ok"
+
+          command_failure("gem install", result)
+        end
+
+        # Environment variables that would drag the INVOKING process's
+        # bundler context into the gem subprocess: RUBYOPT carries
+        # `-rbundler/setup` under `bundle exec ace-lab` (the documented
+        # invocation), RubyGems auto-requires ENV["BUNDLER_SETUP"]
+        # (rubygems.rb), and the BUNDLE_*/BUNDLER_* vars re-bind bundler
+        # when it loads — any of which overrides the pinned paths with
+        # the invoking bundle's load paths. The lab runtime must stay
+        # isolated from the installer's gems, its bundle included.
+        BUNDLER_ENV_KEYS = %w[RUBYOPT RUBYLIB BUNDLER_SETUP BUNDLE_BIN_PATH
+          BUNDLE_GEMFILE BUNDLER_VERSION BUNDLE_BUNDLER_VERSION].freeze
+
+        private_constant :BUNDLER_ENV_KEYS
+
+        # GEM_HOME/GEM_PATH are pinned through the POSIX `env` command so
+        # the argv-array runner seam stays unchanged and the subprocess
+        # sees ONLY the target runtime.
+        def runtime_argv(gem_home, argv)
+          ["env"] +
+            BUNDLER_ENV_KEYS.flat_map { |key| ["-u", key] } +
+            ["GEM_HOME=#{gem_home}", "GEM_PATH=#{gem_home}"] + argv
+        end
+
+        # `gem list <name> --exact --local` prints one `name (v1, v2)`
+        # line when the name is present in the runtime and nothing when
+        # it is absent. A present-but-unparseable line is a failed probe
+        # (nil, fail closed), never a guessed empty list.
+        def parse_versions(out, name)
+          line = out.lines.find { |candidate| candidate.start_with?("#{name} ") }
+          return [] if line.nil?
+
+          match = line.chomp.match(/\A#{Regexp.escape(name)} \((.*)\)\z/)
+          return nil if match.nil?
+
+          match[1].split(",").map(&:strip)
+        end
+
+        # Classified one-line command failure: status plus the first
+        # stderr line only — never command output bodies.
+        def command_failure(command, result)
+          case result["status"]
+          when "enoent"
+            return "#{command} failed: gem not found in PATH; install RubyGems and rerun ace-lab prepare"
+          when "exec_failed"
+            return "#{command} failed: could not be executed (#{result["err"]}); rerun ace-lab prepare"
+          end
+
+          message = "#{command} failed (#{exit_detail(result["status"])})"
+          line = result["err"].to_s.lines.map(&:strip).reject(&:empty?).first
+          message = "#{message}: #{line}" if line
+          "#{message}; rerun ace-lab prepare (with sudo when the runtime is not writable)"
+        end
+
+        def exit_detail(status)
+          status.is_a?(Integer) ? "exit #{status}" : status.to_s
+        end
+
+        def lstat(path)
+          File.lstat(path)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          nil
+        end
+
+        def run_argv(argv)
+          out, err, status = Open3.capture3(*argv)
+          {"status" => status.success? ? "ok" : (status.exitstatus || "signal #{status.termsig}"),
+           "out" => out, "err" => err}
+        rescue Errno::ENOENT
+          {"status" => "enoent", "out" => "", "err" => ""}
+        rescue SystemCallError => e
+          {"status" => "exec_failed", "out" => "", "err" => e.class.name}
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/organisms/install.rb

@@ -19,7 +19,9 @@ module Ace
       #      authorization document must not grant projects this
       #      manifest does not declare — a ready/foreign lab is refused
       #      with a classified error and zero writes;
-      #   2. `Prepare` (L8.1): accounts → directories → keys → roles;
+      #   2. `Prepare` (L8.1): accounts → directories → keys → roles →
+      #      gems (the declared gem set converged into the declared
+      #      target runtime, gad.2);
       #   3. `ProjectAdd` (L8.2) per declared project: repository,
       #      private `_overseer`, project registry, runtime HITL route
       #      configuration (the manifest's `kind: hitl` adapters
@@ -30,12 +32,14 @@ module Ace
       #      make the installed projects visible to `ace-lab projects`
       #      and `ace-overseer projects`;
       #   5. `Verify` (final stage, task 8xg.t.sbz.7.4): the declared
-      #      adapters and required tools are part of the SAME trusted
-      #      manifest (validated at load, reported under `adapters` /
-      #      `tools`), and the converged lab must prove ready UNDER THE
-      #      TARGET ACCOUNTS — tool availability, adapter commands and
-      #      every other readiness check — or install reports not ok.
-      #      Dry runs skip this stage (nothing has converged to verify).
+      #      adapters, required tools and the declared gem set are part
+      #      of the SAME trusted manifest (validated at load, reported
+      #      under `adapters` / `tools` / `gemset`), and the converged
+      #      lab must prove ready UNDER THE
+      #      TARGET ACCOUNTS — tool availability, adapter commands,
+      #      gem-set versions and every other readiness check — or
+      #      install reports not ok. Dry runs skip this stage (nothing
+      #      has converged to verify).
       #
       # Every step is idempotent, so an interrupted re-run converges
       # where steps already completed (the resume contract .7.3 builds
@@ -64,7 +68,7 @@ module Ace
         #   constructor default (the CLI passes its --dry-run here)
         # @return [Hash] aggregated report (ok / dry_run / machine /
         #   manifest / prepare / projects / grants / adapters / tools /
-        #   verify)
+        #   gemset / verify)
         # @raise [Ace::Lab::InvalidConfigurationError] missing, untrusted
         #   or invalid manifest, or a foreign lab refusing overwrite
         #   before any mutation
@@ -123,6 +127,7 @@ module Ace
             "grants" => grants,
             "adapters" => manifest["adapters"],
             "tools" => manifest["tools"],
+            "gemset" => manifest["gemset"],
             "verify" => verify_report
           }
         end

data/lib/ace/lab/organisms/prepare.rb

@@ -6,17 +6,19 @@ require_relative "../molecules/account_provisioner"
 require_relative "../molecules/directory_provisioner"
 require_relative "../molecules/key_provisioner"
 require_relative "../molecules/role_verifier"
+require_relative "../molecules/gemset_provisioner"
 
 module Ace
   module Lab
     module Organisms
       # Orchestrates the preparation phase (L8.1) from the trusted install
-      # manifest: accounts → directories → keys → roles, in that fixed
+      # manifest: accounts → directories → keys → roles → gems, in that fixed
       # order, each through its idempotent provisioner molecule. The
       # aggregated report is the contract consumed by `ace-lab project add`
       # (7.1) and `ace-lab install` (7.2); `ok` means zero failed items.
       # Key and role items whose account failed are reported as dependency
-      # failures instead of being attempted. No state is written beyond
+      # failures instead of being attempted; gem items fail as dependencies
+      # when the declared runtime did not prepare. No state is written beyond
       # what the manifest declares — this organism owns no journal.
       class Prepare
         attr_reader :manifest_path, :dry_run, :platform
@@ -48,16 +50,18 @@ module Ace
           keys = prepare_keys(manifest["keys"], manifest["machine"], manifest["accounts"], available,
             unresolved, effective_dry_run)
           roles = prepare_roles(manifest["roles"], available, unresolved, effective_dry_run)
+          gems = prepare_gems(manifest["gemset"], effective_dry_run)
 
           {
-            "ok" => [accounts, directories, keys, roles].flatten.none? { |item| item["status"] == "failed" },
+            "ok" => [accounts, directories, keys, roles, gems].flatten.none? { |item| item["status"] == "failed" },
             "dry_run" => effective_dry_run,
             "machine" => manifest["machine"],
             "manifest" => manifest_path,
             "accounts" => accounts,
             "directories" => directories,
             "keys" => keys,
-            "roles" => roles
+            "roles" => roles,
+            "gems" => gems
           }
         end
 
@@ -138,6 +142,16 @@ module Ace
           end
         end
 
+        # The declared gem set converged into the declared runtime
+        # (gad.2): machine-level like every other section — independent
+        # of the account phases, gated by its own runtime preparation.
+        def prepare_gems(runtime, dry_run)
+          provisioner = Molecules::GemsetProvisioner.new(
+            runner: @runner, privileged: @privileged, dry_run: dry_run
+          )
+          provisioner.call(runtime: runtime)
+        end
+
         def available_accounts(account_reports)
           account_reports.reject { |report| report["status"] == "failed" }
             .map { |report| report["username"] }

data/lib/ace/lab/organisms/verify.rb

@@ -4,6 +4,7 @@ require_relative "../errors"
 require_relative "../molecules/install_manifest_loader"
 require_relative "../molecules/key_provisioner"
 require_relative "../molecules/role_verifier"
+require_relative "../molecules/gemset_provisioner"
 require_relative "../molecules/hitl_routes"
 require_relative "../molecules/caller_authorizer"
 require_relative "../atoms/topology_schema"
@@ -77,7 +78,7 @@ module Ace
         # @return [Hash] {ready:, machine:, manifest:,
         #   authorization_path:, checks: {accounts:, directories:,
         #   keys:, roles:, repositories:, grants:, registry:,
-        #   overseer:, adapters:, tools:}, counts: {pass:, fail:,
+        #   overseer:, adapters:, tools:, gems:}, counts: {pass:, fail:,
         #   unknown:}}
         # @raise [Ace::Lab::InvalidConfigurationError] missing,
         #   untrusted or schema-invalid manifest — same classification
@@ -97,7 +98,8 @@ module Ace
             "registry" => check_registry(manifest),
             "overseer" => check_overseer(manifest),
             "adapters" => check_adapters(manifest, executors),
-            "tools" => check_tools(manifest, executors)
+            "tools" => check_tools(manifest, executors),
+            "gems" => check_gems(manifest)
           }
           flat = checks.values.flatten(1)
           {
@@ -551,6 +553,72 @@ module Ace
           end
         end
 
+        # Declared gem set (gad.2 gap #1, owner spec 8xg.t.sbz.7): every
+        # declared gem must be installed at its EXACT declared version in
+        # the declared target runtime (GEM_HOME) — read-only, through the
+        # SAME probe the provisioner converges from
+        # (GemsetProvisioner#runtime_versions), so readiness and
+        # convergence can never drift. A missing, symlinked or
+        # non-directory runtime fails every declared gem as a dependency
+        # (nothing could have converged into it); a gem at a wrong or
+        # missing version is a classified failure with an
+        # `ace-lab install` remedy; an environment without the `gem`
+        # executable degrades to unknown (the offline posture) and does
+        # not block by itself. Extra undeclared versions are not judged:
+        # the manifest is the single owner of the DECLARED set.
+        def check_gems(manifest)
+          gemset = manifest["gemset"]
+          gems = gemset["gems"]
+          return [] if gems.empty?
+
+          gem_home = gemset["gem_home"]
+          runtime_reason = gem_runtime_reason(gem_home)
+          provisioner = Molecules::GemsetProvisioner.new(runner: @runner)
+          gems.map do |gem|
+            if runtime_reason
+              next {"gem" => gem["name"], "version" => gem["version"], "gem_home" => gem_home,
+                    "status" => FAIL, "reason" => runtime_reason}
+            end
+
+            kind, versions_or_message = provisioner.runtime_versions(
+              name: gem["name"], gem_home: gem_home
+            )
+            reason = case kind
+            when :unknown, :failed then versions_or_message
+            when :ok then gem_version_reason(gem, versions_or_message, gem_home)
+            end
+            status = case kind
+            when :ok then reason ? FAIL : PASS
+            when :unknown then UNKNOWN
+            else FAIL
+            end
+            {"gem" => gem["name"], "version" => gem["version"], "gem_home" => gem_home,
+             "status" => status, "reason" => reason}
+          end
+        end
+
+        def gem_version_reason(gem, versions, gem_home)
+          return nil if versions.include?(gem["version"])
+          if versions.empty?
+            "gem '#{gem["name"]}' is not installed in gem runtime '#{gem_home}'; " \
+              "rerun ace-lab install"
+          else
+            "gem '#{gem["name"]}' is installed as #{versions.join(", ")} in " \
+              "'#{gem_home}' but the manifest declares #{gem["version"]}; rerun ace-lab install"
+          end
+        end
+
+        def gem_runtime_reason(gem_home)
+          stat = lstat(gem_home)
+          if stat.nil?
+            "gem runtime '#{gem_home}' is missing; rerun ace-lab install"
+          elsif stat.symlink?
+            "gem runtime '#{gem_home}' is a symbolic link"
+          elsif !stat.directory?
+            "'#{gem_home}' exists but is not a directory"
+          end
+        end
+
         # Resolve an executable without running it and judge it for the
         # TARGET EXECUTORS (FINAL-LAB3): a name containing a separator
         # must be a file executable at that path; a bare name must

data/lib/ace/lab/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Lab
-    VERSION = "0.13.0"
+    VERSION = "0.13.1"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-lab
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.13.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -200,6 +200,7 @@ files:
 - lib/ace/lab/molecules/exact_resolver.rb
 - lib/ace/lab/molecules/forge_merge_config.rb
 - lib/ace/lab/molecules/forgejo_merge_adapter.rb
+- lib/ace/lab/molecules/gemset_provisioner.rb
 - lib/ace/lab/molecules/grant_provisioner.rb
 - lib/ace/lab/molecules/grant_resolver.rb
 - lib/ace/lab/molecules/hitl_routes.rb