ace-lab 0.13.1 → 0.14.0

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "fileutils"
+require "pathname"
+
+module Ace
+  module Lab
+    module Molecules
+      # Shared extension-projection primitives (task 8xs.t.pu0.0): the
+      # ONE place that knows how the installed gem's handbook/extensions
+      # tree is located, enumerated, and projected safely — used by both
+      # ExtensionProvisioner (convergence) and Verify (readiness), so
+      # the two can never drift.
+      module ExtensionProjection
+        RECEIPT_NAME = ".ace-lab-extension-projection.json"
+
+        module_function
+
+        # The installed gem's own tree at the EXACT declared version.
+        # @return [String, nil] the handbook/extensions directory or nil
+        #   when the gem (or its extensions tree) is not installed
+        def gem_source_root(gem_home, name, version)
+          candidate = File.join(gem_home, "gems", "#{name}-#{version}")
+          extensions = File.join(candidate, "handbook", "extensions")
+          File.directory?(extensions) ? extensions : nil
+        end
+
+        # Relative path → absolute source file for every file under the
+        # gem's handbook/extensions tree (e.g. "ace-wake/index.js").
+        # @return [Hash<String, String>]
+        def source_files(source_root)
+          Dir.glob(File.join(source_root, "**", "*")).select { |path| File.file?(path) }
+            .to_h { |path| [path.delete_prefix("#{source_root}/"), path] }
+        end
+
+        # Resolve and fully validate a projection destination before
+        # anything is written or verified (the provider_syncer
+        # validate_projection_destination posture): every path
+        # component under the projection directory must be a directory
+        # or creatable — a symlinked component could redirect the
+        # write outside the extensions directory, so it is refused.
+        # @param output_dir [String] manifest-declared extension dir
+        # @param relative_path [String] receipt-relative file path
+        # @return [String] the validated absolute destination
+        # @raise [Ace::Lab::Error] invalid or escaping destination
+        def validate_destination!(output_dir, relative_path)
+          segments = relative_path.to_s.split(File::SEPARATOR)
+          if segments.empty? || segments.any? { |segment| segment.empty? || segment == "." || segment == ".." }
+            raise Ace::Lab::Error, "cannot project #{relative_path.inspect}: invalid destination path"
+          end
+
+          begin
+            current = Pathname.new(File.realpath(output_dir))
+          rescue Errno::ENOENT
+            # the projection directory itself does not exist yet — no
+            # component below it can escape
+            return File.join(output_dir, *segments)
+          end
+          segments.each_with_index do |segment, index|
+            current = current.join(segment)
+            if File.symlink?(current.to_s)
+              raise Ace::Lab::Error,
+                "cannot project #{relative_path} into #{output_dir}: a symlinked path component " \
+                  "would escape the projection directory"
+            end
+            # The FINAL segment is the file itself — only intermediate
+            # components must be directories (compare by position, not
+            # value: "a/a/index.js" repeats "a" legitimately).
+            next if index == segments.size - 1
+
+            if !current.directory? && File.exist?(current.to_s)
+              raise Ace::Lab::Error,
+                "cannot project #{relative_path} into #{output_dir}: #{current} exists and is not a directory"
+            end
+          end
+          if File.directory?(current.to_s)
+            # Receipt ownership of a path never authorizes writing
+            # through a directory planted at that path — cp would
+            # reinterpret the destination as a container.
+            raise Ace::Lab::Error,
+              "cannot project #{relative_path} into #{output_dir}: #{current} exists and is a directory"
+          end
+          current.to_s
+        rescue Errno::ENOENT
+          raise Ace::Lab::Error, "cannot project #{relative_path} into #{output_dir}: projection directory vanished"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "extension_projection"
+require "etc"
+require "fileutils"
+require "json"
+
+module Ace
+  module Lab
+    module Molecules
+      # Projects harness extension assets from an INSTALLED gem's exact
+      # declared version into the manifest-declared extension directory
+      # (task 8xs.t.pu0.0): the manual host-lane copy of the ace-wake
+      # extension is replaced by a converged, repeatable projection.
+      #
+      # Source of truth is the installed gem tree itself —
+      # `<gem_home>/gems/<name>-<version>/handbook/extensions` — so the
+      # projection always matches the exact version the manifest
+      # declared (never the checkout, never a newer gem beside it).
+      # Each target directory carries a receipt
+      # (`.ace-lab-extension-projection.json`) recording the producing
+      # gem, version and file list; ONLY receipt-listed files are ever
+      # removed, so user-authored extensions in the same directory are
+      # never touched. The report names the version that WAS loaded
+      # before this run (`loaded_version`) and whether the projection
+      # changed (`restart_required`) — a changed projection means the
+      # running harness processes still hold the OLD extension; the
+      # installer REPORTS the restart need, it never restarts an
+      # executor on its own.
+      class ExtensionProvisioner
+        RECEIPT_NAME = ExtensionProjection::RECEIPT_NAME
+        FILE_MODE = 0o644
+        DIR_MODE = 0o755
+
+        # @param gem_home [String] target runtime the gems were
+        #   converged into
+        # @param dry_run [Boolean] predict without writing
+        # @param account_lookup [Proc, nil] passwd lookup seam for the
+        #   declared accounts (projection ownership convergence)
+        def initialize(gem_home:, dry_run: false, account_lookup: nil)
+          @gem_home = gem_home
+          @dry_run = dry_run
+          @account_lookup = account_lookup || method(:lookup_passwd)
+        end
+
+        # @param extensions [Array<Hash>] normalized manifest gemset
+        #   extensions entries ({"gem" =>, "path" =>, "account" =>})
+        # @param gems [Array<Hash>] declared gem set (name/version)
+        # @return [Array<Hash>] one report per entry:
+        #   {extension:, gem:, version:, path:, account:, status:,
+        #    loaded_version:, restart_required:, files:, message:}
+        def call(extensions:, gems:)
+          extensions.map do |entry|
+            converge(entry, gems)
+          end
+        end
+
+        private
+
+        def converge(entry, gems)
+          declared = gems.find { |gem| gem["name"] == entry["gem"] }
+          version = declared && declared["version"]
+          source = version && ExtensionProjection.gem_source_root(@gem_home, entry["gem"], version)
+
+          if source.nil?
+            # Fresh-lab dry run (the gem phase predicts would_install
+            # for the same missing gem): predict the projection the
+            # converged gem would feed instead of reporting a failure
+            # the wet run would not produce.
+            if @dry_run
+              return entry_report(entry, version, "would_project", nil, true, [])
+            end
+            return failed(entry, version,
+              "gem '#{entry["gem"]}' is not installed in runtime '#{@gem_home}' at declared " \
+                "version '#{version}'; converge the gemset first (ace-lab install)")
+          end
+
+          expected = ExtensionProjection.source_files(source)
+          if expected.empty?
+            return failed(entry, version,
+              "gem '#{entry["gem"]}' #{version} carries no handbook/extensions tree")
+          end
+
+          output_dir = entry["path"]
+          escape = projection_escape_reason(output_dir, expected.keys)
+          return failed(entry, version, escape) if escape
+
+          receipt = read_receipt(output_dir)
+          loaded_version = receipt && receipt["gem"] == entry["gem"] ? receipt["version"] : nil
+
+          changed = projection_changed?(output_dir, expected, receipt, version)
+          if !changed
+            converge_modes(output_dir, expected, entry)
+            return entry_report(entry, version, "unchanged", loaded_version, false,
+              receipt ? receipt.fetch("files") : expected.keys)
+          end
+          # dry-run predicts the projection (restart needed) without
+          # writing anything
+          return entry_report(entry, version, "projected", loaded_version, true, expected.keys) if @dry_run
+
+          project(output_dir, expected, entry, version)
+          entry_report(entry, version, "projected", loaded_version, true, expected.keys)
+        rescue SystemCallError => e
+          failed(entry, version,
+            "extension projection into '#{output_dir}' failed (#{e.class.name}); " \
+              "rerun ace-lab prepare with sudo or adjust ownership manually")
+        end
+
+        def failed(entry, version, message)
+          entry_report(entry, version, "failed", nil, false, [])
+            .merge("message" => message)
+        end
+
+        def entry_report(entry, version, status, loaded_version, restart_required, files)
+          {"extension" => entry["gem"], "gem" => entry["gem"], "version" => version,
+           "path" => entry["path"], "account" => entry["account"], "status" => status,
+           "loaded_version" => loaded_version, "restart_required" => restart_required,
+           "files" => files, "message" => nil}
+        end
+
+        # Refuse a destination that escapes the projection directory
+        # through a symlinked component BEFORE anything is written (the
+        # provider_syncer validate_projection_destination posture).
+        def projection_escape_reason(output_dir, relative_paths)
+          relative_paths.each { |relative| ExtensionProjection.validate_destination!(output_dir, relative) }
+          nil
+        rescue Ace::Lab::Error => e
+          e.message
+        end
+
+        # A projection changed when the receipt is absent, names a
+        # different version, lists a different file set, or any
+        # expected file's content differs on disk.
+        def projection_changed?(output_dir, expected, receipt, version)
+          return true if receipt.nil?
+          return true if receipt["version"] != version
+          return true unless receipt.fetch("files", []).sort == expected.keys.sort
+
+          expected.any? do |relative, source|
+            target = File.join(output_dir, relative)
+            !File.file?(target) || !FileUtils.compare_file(source, target)
+          end
+        end
+
+        def project(output_dir, expected, entry, version)
+          FileUtils.mkdir_p(output_dir)
+          expected.each do |relative, source|
+            target = File.join(output_dir, relative)
+            FileUtils.mkdir_p(File.dirname(target))
+            FileUtils.cp(source, target)
+          end
+
+          # Only receipt-owned files no longer in the projection are
+          # removed; a removal that fails keeps its receipt entry so a
+          # later run retries it (user-authored extensions are never
+          # touched).
+          previous = read_receipt(output_dir)&.fetch("files", []) || []
+          retained = previous.filter_map do |relative|
+            target = File.join(output_dir, relative)
+            next relative if expected.key?(relative)
+
+            FileUtils.rm_f(target)
+            File.exist?(target) ? relative : nil
+          end
+
+          write_receipt(output_dir, entry, version, (expected.keys + retained).sort)
+          converge_modes(output_dir, expected, entry)
+        end
+
+        # Mode/ownership convergence (the key-provisioner posture):
+        # projected files carry owner read/write plus world read
+        # (0644), projection directories 0755, and both are owned by
+        # the declared account whenever the passwd lookup resolves it —
+        # so the target executor can always read its extensions.
+        def converge_modes(output_dir, expected, entry)
+          account = @account_lookup.call(entry["account"])
+          targets = expected.keys.map { |relative| File.join(output_dir, relative) }
+          targets << File.join(output_dir, RECEIPT_NAME)
+          targets.each do |target|
+            next unless File.file?(target)
+
+            FileUtils.chmod(FILE_MODE, target)
+            FileUtils.chown(account.uid, account.gid, target) if account
+          end
+          root = File.realpath(output_dir)
+          dirs = expected.keys.filter_map do |relative|
+            File.dirname(File.join(root, relative)) if relative.include?(File::SEPARATOR)
+          end.uniq
+          until dirs.empty?
+            dir = dirs.pop
+            FileUtils.chmod(DIR_MODE, dir)
+            FileUtils.chown(account.uid, account.gid, dir) if account
+            parent = File.dirname(dir)
+            dirs << parent if dir != root && parent.start_with?("#{root}/") && !dirs.include?(parent) && parent != root
+          end
+        end
+
+        def write_receipt(output_dir, entry, version, files)
+          document = {
+            "gem" => entry["gem"], "version" => version,
+            "projected_at" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "files" => files.sort
+          }
+          File.write(File.join(output_dir, RECEIPT_NAME), JSON.pretty_generate(document))
+        end
+
+        def read_receipt(output_dir)
+          path = File.join(output_dir, RECEIPT_NAME)
+          return nil unless File.file?(path)
+
+          document = JSON.parse(File.read(path))
+          document.is_a?(Hash) ? document : nil
+        rescue JSON::ParserError, Errno::EACCES
+          nil
+        end
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -49,7 +49,12 @@ module Ace
             if runtime_failure
               base(gem, gem_home).merge("status" => "failed", "message" => runtime_failure)
             else
-              converge(base(gem, gem_home), gem, gem_home)
+              report = converge(base(gem, gem_home), gem, gem_home)
+              if %w[exists installed updated].include?(report["status"])
+                converge_post_presence(report, gem, gem_home)
+              else
+                report
+              end
             end
           end
         end
@@ -78,6 +83,55 @@ module Ace
           [:ok, versions]
         end
 
+        # Public READ-ONLY probes (verify, task 8xs.t.pu0.0): the same
+        # primitives convergence runs, exposed so readiness reuses the
+        # identical logic instead of reimplementing it.
+        #
+        # Unsatisfied runtime dependencies of the declared gem — the
+        # concrete missing-dependency list readiness reports.
+        # @return [Array(Symbol, Object)] [:ok, reasons] (empty reasons
+        #   = closed) or the failing probe's [:unknown/:failed,
+        #   message] — the same shape newer_versions returns.
+        def closure_failures(name:, version:, gem_home:)
+          queue = [[name, version]]
+          seen = {}
+          reasons = []
+          until queue.empty?
+            current_name, current_version = queue.shift
+            next if seen[[current_name, current_version]]
+
+            seen[[current_name, current_version]] = true
+            deps = runtime_dependencies(name: current_name, version: current_version, gem_home: gem_home)
+            return [:failed, deps] if deps.is_a?(String)
+
+            deps.each do |dep|
+              kind, versions_or_message = runtime_versions(name: dep["name"], gem_home: gem_home)
+              return [kind, versions_or_message] if kind != :ok
+
+              satisfying = satisfying_versions(dep, versions_or_message)
+              if satisfying.empty?
+                reasons << "dependency '#{dep["name"]} (#{dep["requirement"]})' required by gem " \
+                  "'#{current_name}' is not satisfied in runtime '#{gem_home}'"
+              else
+                queue << [dep["name"], satisfying.max_by { |v| Gem::Version.new(v) }]
+              end
+            end
+          end
+          [:ok, reasons]
+        end
+
+        # Installed versions of `name` NEWER than the declared one —
+        # the versions that would win activation and take over the CLI.
+        # @return [Array(String, Object)] [:ok, versions] or the probe's
+        #   [:unknown/:failed, message]
+        def newer_versions(name:, declared_version:, gem_home:)
+          kind, versions_or_message = runtime_versions(name: name, gem_home: gem_home)
+          return [kind, versions_or_message] if kind != :ok
+
+          declared = Gem::Version.new(declared_version)
+          [:ok, versions_or_message.select { |version| Gem::Version.new(version) > declared }]
+        end
+
         private
 
         def base(gem, gem_home)
@@ -132,6 +186,153 @@ module Ace
           end
         end
 
+        # Post-presence convergence (task 8xs.t.pu0.0): the declared
+        # version being present is necessary but not sufficient.
+        #   1. NEWER versions of the declared gem sitting beside the
+        #      declared one would win RubyGems activation and take over
+        #      the runtime's CLI — the manifest is the single owner of
+        #      the declared set, so convergence removes them from the
+        #      target runtime.
+        #   2. The dependency closure must actually resolve in the
+        #      runtime: a gem whose version already figures in
+        #      `gem list` can still miss a transitive runtime
+        #      dependency (the manually-repaired `json` class of gap);
+        #      missing dependencies are converged by installing them
+        #      at the parent's requirement, and an unsatisfiable
+        #      dependency is a classified failure — never readiness.
+        # A dry run predicts both without writing (would_uninstall /
+        # would_install) and stops recursion at the prediction.
+        def converge_post_presence(report, gem, gem_home)
+          removal = converge_newer_versions(gem, gem_home)
+          return report.merge("status" => "failed", "message" => removal) if removal.is_a?(String)
+          report["removed_newer_versions"] = removal
+
+          closure = converge_closure(gem, gem_home)
+          return report.merge("status" => "failed", "message" => closure) if closure.is_a?(String)
+          report["closure"] = closure
+          report
+        end
+
+        # @return [Array<Hash>, String] per-version removal reports or a
+        #   classified failure message
+        def converge_newer_versions(gem, gem_home)
+          kind, versions_or_message = runtime_versions(name: gem["name"], gem_home: gem_home)
+          return versions_or_message if kind != :ok
+
+          declared = Gem::Version.new(gem["version"])
+          newer = versions_or_message.select { |version| Gem::Version.new(version) > declared }
+          return [] if newer.empty?
+
+          return newer.map { |version| {"version" => version, "status" => "would_uninstall"} } if @dry_run
+
+          newer.map do |version|
+            result = @runner.call(runtime_argv(gem_home,
+              ["gem", "uninstall", gem["name"], "--version", version, "-x", "--force"]))
+            if result["status"] != "ok"
+              break command_failure("gem uninstall #{gem["name"]} #{version}", result)
+            end
+            {"version" => version, "status" => "uninstalled"}
+          end
+        end
+
+        # Breadth-first walk of the gem's RUNTIME dependency closure in
+        # the target runtime. `gem dependency` output is plain text (no
+        # marshaled objects), development dependencies are ignored.
+        # @return [Array<Hash>, String] per-dependency convergence
+        #   actions or a classified failure message
+        def converge_closure(gem, gem_home)
+          queue = [[gem["name"], gem["version"]]]
+          seen = {}
+          actions = []
+          until queue.empty?
+            name, version = queue.shift
+            next if seen[[name, version]]
+
+            seen[[name, version]] = true
+            deps = runtime_dependencies(name: name, version: version, gem_home: gem_home)
+            return deps if deps.is_a?(String)
+
+            deps.each do |dep|
+              kind, versions_or_message = runtime_versions(name: dep["name"], gem_home: gem_home)
+              return versions_or_message if kind != :ok
+
+              satisfying = satisfying_versions(dep, versions_or_message)
+              if satisfying.empty?
+                if @dry_run
+                  actions << {"name" => dep["name"], "requirement" => dep["requirement"],
+                              "status" => "would_install"}
+                  next # recursion stops at the prediction
+                end
+
+                failure = install_dependency(dep, gem_home)
+                return failure if failure
+
+                kind, versions_or_message = runtime_versions(name: dep["name"], gem_home: gem_home)
+                return versions_or_message if kind != :ok
+                satisfying = satisfying_versions(dep, versions_or_message)
+                if satisfying.empty?
+                  return "dependency '#{dep["name"]} (#{dep["requirement"]})' required by gem " \
+                    "'#{name}' is not satisfiable in runtime '#{gem_home}' after install; " \
+                    "check the gem source or the manifest declaration"
+                end
+                actions << {"name" => dep["name"], "requirement" => dep["requirement"],
+                            "status" => "installed"}
+              end
+
+              chosen = satisfying.max_by { |v| Gem::Version.new(v) }
+              queue << [dep["name"], chosen]
+            end
+          end
+          actions
+        end
+
+        # Installs a missing dependency at the parent requirement: the
+        # requirement string the runtime's own resolver would accept
+        # (`gem install name -v "~> 2.7"`).
+        # @return [String, nil] classified failure, nil on success
+        def install_dependency(dep, gem_home)
+          result = @runner.call(runtime_argv(gem_home,
+            ["gem", "install", dep["name"], "--version", dep["requirement"], "--no-document"]))
+          return nil if result["status"] == "ok"
+
+          command_failure("gem install #{dep["name"]}", result)
+        end
+
+        # The runtime (non-development) dependencies of an installed
+        # gem, from `gem dependency <name> --version <v>` plain-text
+        # output: "dep (~> 2.0, runtime)" lines under the gem header.
+        # @return [Array<Hash{"name","requirement"}>, String] or a
+        #   classified failure message
+        def runtime_dependencies(name:, version:, gem_home:)
+          result = @runner.call(runtime_argv(gem_home,
+            ["gem", "dependency", name, "--version", version]))
+          if result["status"] == "enoent"
+            return "gem not found in PATH; install RubyGems and rerun ace-lab prepare"
+          end
+          return "gem dependency failed (#{exit_detail(result["status"])}); rerun ace-lab prepare" \
+            unless result["status"] == "ok"
+
+          result["out"].lines.filter_map do |line|
+            match = line.match(/\A\s+([A-Za-z0-9._-]+) \(([^)]*)\)\s*\z/)
+            next if match.nil?
+
+            parts = match[2].split(",").map(&:strip)
+            type = %w[runtime development].include?(parts.last) ? parts.pop : "runtime"
+            next if type == "development"
+
+            requirement = parts.join(", ")
+            requirement = ">= 0" if requirement.empty?
+            {"name" => match[1], "requirement" => requirement}
+          end
+        end
+
+        def satisfying_versions(dep, versions)
+          requirement = dep["requirement"].split(",").map(&:strip)
+          versions.select do |version|
+            Gem::Dependency.new(dep["name"], *requirement).match?(dep["name"], version)
+          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
@@ -169,8 +370,16 @@ module Ace
 
         # `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.
+        # it is absent. A DEFAULT gem's bundled version appears as a
+        # `default: V` part (`abbrev (default: 0.1.2)`,
+        # `json (2.9.4, default: 2.9.1)`): the marked V is the default
+        # gem's own version, every other part is an additionally
+        # installed version — both are present in the runtime, so the
+        # normalized list carries the marked version in place of the
+        # marker. Every candidate is validated by Gem::Version itself —
+        # platform-suffixed or otherwise malformed strings fail the
+        # probe (nil, fail closed) instead of crashing a later
+        # Gem::Version.new caller; never a guessed empty list.
         def parse_versions(out, name)
           line = out.lines.find { |candidate| candidate.start_with?("#{name} ") }
           return [] if line.nil?
@@ -178,7 +387,17 @@ module Ace
           match = line.chomp.match(/\A#{Regexp.escape(name)} \((.*)\)\z/)
           return nil if match.nil?
 
-          match[1].split(",").map(&:strip)
+          versions = match[1].split(",").map(&:strip).map do |part|
+            default = part.match(/\Adefault: (\S+)\z/)
+            default ? default[1] : part
+          end
+          begin
+            versions.each { |version| Gem::Version.new(version) }
+          rescue ArgumentError
+            return nil
+          end
+
+          versions
         end
 
         # Classified one-line command failure: status plus the first

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Lab
+    module Molecules
+      # INTERNAL project-location read for the lab-level overseer start
+      # (task 8xs.t.pu0.a): the project list and their CANONICAL
+      # locations come from the raw topology configuration
+      # (`topology.projects`: id/path) read at the lab root — the schema
+      # normalization and the public projection deliberately strip paths,
+      # so this reader goes to the raw cascade document and takes only
+      # what the start needs. Locations are never derived from a public
+      # id/label or a repo name. The public CLI keeps its allowlisted
+      # projection; only the start operation consumes locations,
+      # in-process.
+      class ProjectLocations
+        # @param lab_root [String] lab coordination directory whose
+        #   cascade lists the configured projects
+        # @return [Array<Hash>] {"id" =>, "path" =>} sorted by id; a
+        #   project entry without a usable path is returned with a nil
+        #   path so its OWN start reports the concrete error
+        # @raise [Ace::Lab::InvalidConfigurationError] the topology
+        #   configuration could not be read or has no project list
+        def self.read(lab_root)
+          config_path = File.join(lab_root, ".ace/lab/config.yml")
+          document = YAML.safe_load_file(config_path,
+            permitted_classes: [Date], aliases: true)
+          unless document.is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError, ".ace/lab/config.yml must be a mapping"
+          end
+
+          raw = document.dig("topology", "projects")
+          unless raw.is_a?(Array)
+            raise Ace::Lab::InvalidConfigurationError,
+              "topology.projects must be a list in .ace/lab/config.yml"
+          end
+
+          raw.map do |entry|
+            next {"id" => nil, "path" => nil} unless entry.is_a?(Hash)
+
+            # A nil/blank path encoding is returned as a nil path (the
+            # project's OWN start reports the concrete error) — never a
+            # bogus empty-string path, never an exception. The config is
+            # read by explicit path: no global cwd mutation.
+            path = entry["path"]
+            path = nil unless path.is_a?(String) && !path.strip.empty?
+            {"id" => entry["id"].to_s, "path" => path}
+          end.sort_by { |project| project["id"].to_s }
+        rescue Errno::ENOENT
+          raise Ace::Lab::InvalidConfigurationError,
+            "no lab configuration at #{lab_root}/.ace/lab/config.yml; run " \
+              "ace-lab project add or fix the lab root"
+        rescue Psych::SyntaxError => e
+          raise Ace::Lab::InvalidConfigurationError,
+            "lab configuration could not be parsed: #{e.message}"
+        end
+      end
+    end
+  end
+end