ace-lab 0.1.0

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

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ace
+  module Lab
+    module Atoms
+      # Pure schema validation and normalization for ace-lab topology
+      # configuration (spec 8wq.t.1w4). Takes the ADR-022-resolved config hash
+      # and returns a normalized structure; raises
+      # Ace::Lab::InvalidConfigurationError on any violation (duplicate IDs,
+      # unknown project references, malformed capabilities, invalid defaults,
+      # unusable endpoints, unsupported schema version).
+      #
+      # Normalization: strings are stripped, capabilities are lowercased,
+      # binding state is lowercased. Unknown keys are ignored.
+      #
+      # Error messages use positional field locations (e.g.
+      # "topology.agents[0].project") and never echo configured values:
+      # validation runs before authorization, so messages must not disclose
+      # topology to unauthorized callers (review round 2, R2).
+      module TopologySchema
+        SCHEMA_VERSION = 1
+        ENDPOINT_KINDS = %w[http https].freeze
+        # Bindings are entry-typed: agents run in runtimes, services are
+        # service endpoints (review round 4, F1)
+        AGENT_BINDING_KINDS = %w[runtime].freeze
+        SERVICE_BINDING_KINDS = %w[service].freeze
+
+        class << self
+          # Validate and normalize the full lab configuration
+          #
+          # @param config [Hash] ADR-022-resolved configuration
+          # @return [Hash] Normalized configuration
+          # @raise [Ace::Lab::InvalidConfigurationError]
+          def normalize!(config)
+            raise invalid("configuration must be a mapping") unless config.is_a?(Hash)
+
+            version = config["schema_version"]
+            unless version == SCHEMA_VERSION
+              raise invalid("unsupported schema_version (expected #{SCHEMA_VERSION})")
+            end
+
+            topology = normalized_topology(config["topology"])
+            authorization = normalized_authorization(config["authorization"], topology)
+
+            {
+              "schema_version" => SCHEMA_VERSION,
+              "authorization" => authorization,
+              "topology" => topology
+            }
+          end
+
+          private
+
+          def normalized_topology(raw)
+            raise invalid("topology must be a mapping") unless raw.nil? || raw.is_a?(Hash)
+
+            raw ||= {}
+            projects = require_array(raw["projects"], "topology.projects").map.with_index do |entry, i|
+              normalized_project(entry, "topology.projects[#{i}]")
+            end
+            project_ids = projects.map { |p| p["id"] }
+            agents = require_array(raw["agents"], "topology.agents").map.with_index do |entry, i|
+              normalized_agent(entry, "topology.agents[#{i}]", project_ids)
+            end
+            services = require_array(raw["services"], "topology.services").map.with_index do |entry, i|
+              normalized_service(entry, "topology.services[#{i}]", project_ids)
+            end
+
+            ensure_globally_unique!(projects, agents, services)
+
+            {"projects" => projects, "agents" => agents, "services" => services}
+          end
+
+          def normalized_project(entry, context)
+            raise invalid("#{context} must be a mapping") unless entry.is_a?(Hash)
+
+            {
+              "id" => require_id(entry["id"], "#{context}.id"),
+              "label" => optional_string(entry["label"], "#{context}.label")
+            }
+          end
+
+          def normalized_agent(entry, context, project_ids)
+            raise invalid("#{context} must be a mapping") unless entry.is_a?(Hash)
+
+            id = require_id(entry["id"], "#{context}.id")
+            project = require_project_ref(entry["project"], "#{context}.project", project_ids)
+
+            {
+              "id" => id,
+              "project" => project,
+              "label" => optional_string(entry["label"], "#{context}.label"),
+              "role" => require_non_empty(entry["role"], "#{context}.role must be a non-empty string"),
+              "capabilities" => normalize_capabilities(entry["capabilities"], "#{context}.capabilities"),
+              "binding" => normalize_binding(entry["binding"], "#{context}.binding", AGENT_BINDING_KINDS)
+            }
+          end
+
+          def normalized_service(entry, context, project_ids)
+            raise invalid("#{context} must be a mapping") unless entry.is_a?(Hash)
+
+            id = require_id(entry["id"], "#{context}.id")
+            project = require_project_ref(entry["project"], "#{context}.project", project_ids)
+            capabilities = normalize_capabilities(entry["capabilities"], "#{context}.capabilities")
+
+            {
+              "id" => id,
+              "project" => project,
+              "label" => optional_string(entry["label"], "#{context}.label"),
+              "capabilities" => capabilities,
+              "default_for" => normalize_default_for(entry["default_for"], "#{context}.default_for", capabilities),
+              "endpoint" => normalize_endpoint(entry["endpoint"], "#{context}.endpoint"),
+              "binding" => normalize_binding(entry["binding"], "#{context}.binding", SERVICE_BINDING_KINDS)
+            }
+          end
+
+          def ensure_globally_unique!(projects, agents, services)
+            seen = Hash.new { |h, k| h[k] = [] }
+            projects.each_with_index { |e, i| seen[e["id"]] << "topology.projects[#{i}]" }
+            agents.each_with_index { |e, i| seen[e["id"]] << "topology.agents[#{i}]" }
+            services.each_with_index { |e, i| seen[e["id"]] << "topology.services[#{i}]" }
+
+            _id, locations = seen.find { |_key, list| list.length > 1 }
+            return unless locations
+
+            raise invalid("duplicate stable id: #{locations.join(" and ")} define the same id; " \
+                          "stable IDs must be globally unique")
+          end
+
+          def normalized_authorization(raw, topology)
+            raise invalid("authorization must be a mapping") unless raw.nil? || raw.is_a?(Hash)
+
+            raw ||= {}
+            principals_raw = raw["principals"]
+            unless principals_raw.nil? || principals_raw.is_a?(Hash)
+              raise invalid("authorization.principals must be a mapping")
+            end
+
+            project_ids = topology["projects"].map { |p| p["id"] }
+            principals = (principals_raw || {}).map.with_index do |(principal, policy), i|
+              context = "authorization.principals[#{i}]"
+              name = require_non_empty(principal, "#{context} name must be a non-empty string")
+              raise invalid("#{context} policy must be a mapping") unless policy.is_a?(Hash)
+
+              allowed = require_array(policy["projects"], "#{context}.projects").map.with_index do |project, j|
+                unless project_ids.include?(project)
+                  raise invalid("#{context}.projects[#{j}] references an unknown project")
+                end
+
+                project
+              end
+              [name, {"projects" => allowed.uniq}]
+            end
+
+            {"principals" => principals.to_h}
+          end
+
+          def require_id(value, context)
+            require_non_empty(value, "#{context} must be a non-empty string")
+          end
+
+          # Malformed collections must classify as invalid_configuration, not
+          # crash with NoMethodError/TypeError mid-iteration (review R2)
+          def require_array(value, context)
+            return [] if value.nil?
+            raise invalid("#{context} must be an array") unless value.is_a?(Array)
+
+            value
+          end
+
+          def require_project_ref(value, context, project_ids)
+            project = require_non_empty(value, "#{context} must be a non-empty string")
+            unless project_ids.include?(project)
+              raise invalid("#{context} references an unknown project")
+            end
+
+            project
+          end
+
+          def normalize_capabilities(value, context)
+            unless value.is_a?(Array)
+              raise invalid("#{context} must be a non-empty array of strings")
+            end
+
+            capabilities = value.map do |capability|
+              require_non_empty(capability, "#{context} entry must be a non-empty string").downcase
+            end
+            unless capabilities.any?
+              raise invalid("#{context} must be a non-empty array of strings")
+            end
+
+            capabilities.uniq
+          end
+
+          def normalize_default_for(value, context, capabilities)
+            return [] if value.nil?
+            unless value.is_a?(Array)
+              raise invalid("#{context} must be an array of capabilities")
+            end
+
+            value.map do |capability|
+              normalized = require_non_empty(capability, "#{context} entry must be a non-empty string").downcase
+              unless capabilities.include?(normalized)
+                raise invalid("#{context} entry does not match a declared capability")
+              end
+
+              normalized
+            end.uniq
+          end
+
+          def normalize_endpoint(value, context)
+            unless value.is_a?(Hash)
+              raise invalid("#{context} must be a mapping with kind and url")
+            end
+
+            kind = require_non_empty(value["kind"], "#{context}.kind must be a non-empty string").downcase
+            unless ENDPOINT_KINDS.include?(kind)
+              raise invalid("#{context}.kind must be one of: #{ENDPOINT_KINDS.join(", ")}")
+            end
+
+            url = require_non_empty(value["url"], "#{context}.url must be a non-empty string")
+            validate_endpoint_url(url, context)
+
+            {"kind" => kind, "url" => url}
+          end
+
+          # A malformed endpoint must fail configuration loading, never
+          # become a routing candidate with an empty public identity
+          # (review round 2, R1). Port bounds included: Ruby's URI parser
+          # accepts out-of-range ports (review round 4, F2).
+          def validate_endpoint_url(url, context)
+            uri = URI.parse(url)
+            usable = (uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)) &&
+              uri.host && !uri.host.empty? &&
+              uri.port.is_a?(Integer) && (1..65_535).cover?(uri.port)
+            raise invalid("#{context}.url must be an absolute http(s) URL with a host and a valid port") unless usable
+          rescue URI::Error, ArgumentError
+            raise invalid("#{context}.url must be an absolute http(s) URL with a host and a valid port")
+          end
+
+          def normalize_binding(value, context, allowed_kinds)
+            unless value.is_a?(Hash)
+              raise invalid("#{context} must be a mapping")
+            end
+
+            kind = require_non_empty(value["kind"], "#{context}.kind must be a non-empty string").downcase
+            unless allowed_kinds.include?(kind)
+              raise invalid("#{context}.kind must be one of: #{allowed_kinds.join(", ")}")
+            end
+
+            {
+              "kind" => kind,
+              "state" => optional_string(value["state"], "#{context}.state")&.downcase,
+              "instance_id" => optional_string(value["instance_id"], "#{context}.instance_id"),
+              "attested_instance_id" => optional_string(value["attested_instance_id"], "#{context}.attested_instance_id")
+            }
+          end
+
+          def require_non_empty(value, message)
+            raise invalid(message) unless value.is_a?(String) && !value.strip.empty?
+
+            value.strip
+          end
+
+          def optional_string(value, context)
+            return nil if value.nil?
+
+            require_non_empty(value, "#{context} must be a non-empty string")
+          end
+
+          def invalid(message)
+            Ace::Lab::InvalidConfigurationError.new("invalid lab configuration: #{message}")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Agents < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            List lab agents in a project by stable ID
+
+            Agents are disclosed only to callers authorized for the project;
+            runtime pane/session bindings are never exposed.
+          DESC
+
+          example ["--project atlas --format json"]
+
+          option :project, type: :string, required: true, desc: "Project stable ID"
+          option :format, type: :string, desc: "Output format (json only)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(topology_service: nil)
+            @topology_service = topology_service
+          end
+
+          def call(project:, **options)
+            ensure_json_format!(options)
+            reject_identity_flags!(options)
+
+            emit_result(topology_service.agents(project: project), quiet: options[:quiet])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Projects < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            List lab projects visible to the verified caller
+
+            Only projects covered by a configured authorization principal are
+            returned; a caller with no principal receives a classified
+            unauthorized error.
+          DESC
+
+          example ["--format json"]
+
+          option :format, type: :string, desc: "Output format (json only)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(topology_service: nil)
+            @topology_service = topology_service
+          end
+
+          def call(**options)
+            ensure_json_format!(options)
+            reject_identity_flags!(options)
+
+            emit_result(topology_service.projects, quiet: options[:quiet])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Resolve < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Resolve one lab entry by exact stable ID
+
+            Labels are display values and never resolve; an unknown ID is a
+            classified missing error, a replaced process a classified stale
+            error.
+          DESC
+
+          example ["--id atlas-planner --format json"]
+
+          option :id, type: :string, required: true, desc: "Stable entry ID"
+          option :format, type: :string, desc: "Output format (json only)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(topology_service: nil)
+            @topology_service = topology_service
+          end
+
+          def call(id:, **options)
+            ensure_json_format!(options)
+            reject_identity_flags!(options)
+
+            emit_result(topology_service.resolve(id: id), quiet: options[:quiet])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Route < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Select a configured capable service in a project
+
+            Routing never invokes a service or grants credentials; zero
+            candidates are missing, several without a configured default are
+            ambiguous.
+          DESC
+
+          example ["--project atlas --capability search --format json"]
+
+          option :project, type: :string, required: true, desc: "Project stable ID"
+          option :capability, type: :string, required: true, desc: "Capability to route"
+          option :format, type: :string, desc: "Output format (json only)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(topology_service: nil)
+            @topology_service = topology_service
+          end
+
+          def call(project:, capability:, **options)
+            ensure_json_format!(options)
+            reject_identity_flags!(options)
+
+            emit_result(
+              topology_service.route(project: project, capability: capability),
+              quiet: options[:quiet]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Services < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            List lab services in a project by stable ID
+
+            Endpoints are sanitized to scheme/host identity; tokens, auth
+            files, userinfo, query parameters, and fragments never appear.
+          DESC
+
+          example ["--project atlas --format json"]
+
+          option :project, type: :string, required: true, desc: "Project stable ID"
+          option :format, type: :string, desc: "Output format (json only)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(topology_service: nil)
+            @topology_service = topology_service
+          end
+
+          def call(project:, **options)
+            ensure_json_format!(options)
+            reject_identity_flags!(options)
+
+            emit_result(topology_service.services(project: project), quiet: options[:quiet])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        # Shared collaborator construction for ace-lab commands. The topology
+        # service is injectable so tests can substitute fixtures; registered
+        # commands resolve the ADR-022 cascade. Output is deterministic JSON
+        # only; classified failures emit one error document and then raise
+        # for a non-zero exit (ADR-023).
+        module Runtime
+          def topology_service
+            @topology_service ||= Organisms::TopologyService.from_config
+          end
+
+          # The interface accepts only JSON; anything else is a usage error
+          def ensure_json_format!(options)
+            format = options[:format]
+            return if format.nil? || format == "json"
+
+            cli_error("--format #{format.inspect} is not supported; only --format json is available")
+          end
+
+          # Caller identity is derived from the verified local process owner.
+          # Role/principal flags would blur the authorization boundary and are
+          # rejected outright (spec 8wq.t.1w4).
+          def reject_identity_flags!(options)
+            spoofed = %i[role principal caller].select { |flag| options[flag] }
+            return if spoofed.empty?
+
+            cli_error("--#{spoofed.first.to_s.tr("_", "-")} is not supported; caller identity is derived " \
+                      "from the verified local process owner")
+          end
+
+          # Emit the result envelope; classified errors still print exactly
+          # one deterministic JSON document before failing
+          def emit_result(result, quiet: false)
+            envelope = result.envelope
+            puts JSON.generate(envelope) unless quiet
+            return if result.ok?
+
+            raise Ace::Support::Cli::Error, "#{envelope["error"]["code"]}: #{envelope["error"]["message"]}"
+          end
+
+          def cli_error(message)
+            raise Ace::Support::Cli::Error, message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../lab"
+require_relative "cli/commands/projects"
+require_relative "cli/commands/agents"
+require_relative "cli/commands/services"
+require_relative "cli/commands/resolve"
+require_relative "cli/commands/route"
+
+module Ace
+  module Lab
+    # ace-support-cli based CLI registry for ace-lab
+    module CLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-lab"
+
+      # Application commands with descriptions (for help output)
+      REGISTERED_COMMANDS = [
+        ["projects", "List lab projects visible to the verified caller"],
+        ["agents", "List lab agents in a project by stable ID"],
+        ["services", "List lab services in a project by stable ID"],
+        ["resolve", "Resolve one lab entry by exact stable ID"],
+        ["route", "Select a configured capable service in a project"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        "ace-lab projects --format json",
+        "ace-lab agents --project atlas --format json",
+        "ace-lab resolve --id atlas-planner --format json",
+        "ace-lab route --project atlas --capability search --format json"
+      ].freeze
+
+      # Start the CLI
+      #
+      # @param args [Array<String>] Command-line arguments
+      # @return [Integer] Exit code (0 for success, non-zero for failure)
+      def self.start(args)
+        Ace::Support::Cli::Runner.new(self).call(args: args)
+      end
+
+      # Register application commands
+      register "projects", CLI::Commands::Projects.new
+      register "agents", CLI::Commands::Agents.new
+      register "services", CLI::Commands::Services.new
+      register "resolve", CLI::Commands::Resolve.new
+      register "route", CLI::Commands::Route.new
+
+      # Register version command
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-lab",
+        version: Ace::Lab::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      # Register help command
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Lab::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+    end
+  end
+end

data/lib/ace/lab/models/query_result.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Models
+      # Immutable classified result of a topology query (spec 8wq.t.1w4).
+      # Either ok with public data, or a classified error with one of the
+      # ERROR_CODES. Serialized as the deterministic JSON envelope:
+      #   {"status":"ok","data":{...}}
+      #   {"status":"error","error":{"code":...,"message":...,...}}
+      class QueryResult
+        ERROR_CODES = %w[missing ambiguous stale unauthorized invalid_configuration].freeze
+
+        attr_reader :data, :error_code, :message, :context
+
+        def initialize(data: nil, error_code: nil, message: nil, context: {})
+          if error_code.nil? && message.nil?
+            @data = data
+          else
+            unless ERROR_CODES.include?(error_code)
+              raise ArgumentError, "unknown error code: #{error_code.inspect}"
+            end
+
+            @error_code = error_code
+            @message = message
+            @context = context.dup.freeze
+          end
+          freeze
+        end
+
+        def self.ok(data)
+          new(data: data)
+        end
+
+        def self.failure(code, message, **context)
+          new(error_code: code, message: message, context: context)
+        end
+
+        def ok?
+          (!error_code.nil?) ? false : true
+        end
+
+        def envelope
+          if ok?
+            {"status" => "ok", "data" => data}
+          else
+            error = {"code" => error_code, "message" => message}
+            error.merge!(context.select { |_k, v| !v.nil? })
+            {"status" => "error", "error" => error}
+          end
+        end
+      end
+    end
+  end
+end