ace-lab 0.1.0

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Organisms
+      # Public query facade for all ace-lab CLI commands (spec 8wq.t.1w4):
+      # loads and validates topology, derives the verified caller identity,
+      # and returns classified QueryResults. Read-only by contract — it never
+      # invokes a service, grants credentials, or creates any state.
+      class TopologyService
+        # Build a service from configuration (ADR-022 cascade when omitted).
+        # Normalization happens lazily inside the classified boundary so
+        # configuration defects surface as invalid_configuration results.
+        def self.from_config(config = nil)
+          new(config: config)
+        end
+
+        # @param config [Hash, nil] pre-supplied configuration to normalize
+        # @param loader [Molecules::TopologyLoader, nil] injected loader
+        # @param authorizer [Molecules::CallerAuthorizer, nil] injected authorizer
+        # @raise [ArgumentError] when only one of loader/authorizer is
+        #   injected — partial injection would silently mix collaborators
+        #   (subject review: honor independently injected collaborators)
+        def initialize(config: nil, loader: nil, authorizer: nil)
+          if loader.nil? != authorizer.nil?
+            raise ArgumentError, "loader and authorizer must be injected together or both omitted"
+          end
+
+          @config = config
+          @loader = loader
+          @authorizer = authorizer
+        end
+
+        def projects
+          query { |index, authorizer| Molecules::InventoryQuery.new(index: index, authorizer: authorizer).projects }
+        end
+
+        def agents(project:)
+          query do |index, authorizer|
+            Molecules::InventoryQuery.new(index: index, authorizer: authorizer).agents(project: project)
+          end
+        end
+
+        def services(project:)
+          query do |index, authorizer|
+            Molecules::InventoryQuery.new(index: index, authorizer: authorizer).services(project: project)
+          end
+        end
+
+        def resolve(id:)
+          query { |index, authorizer| Molecules::ExactResolver.new(index: index, authorizer: authorizer).resolve(id) }
+        end
+
+        def route(project:, capability:)
+          query do |index, authorizer|
+            Molecules::CapabilityRouter.new(index: index, authorizer: authorizer)
+              .route(project: project, capability: capability)
+          end
+        end
+
+        private
+
+        # Run a query against the validated index. Configuration loading,
+        # schema validation, and authorization derivation all happen inside
+        # this boundary so every defect classifies as invalid_configuration
+        # (review R4) and authorization always uses the normalized document
+        # the topology was validated against (review R3).
+        def query
+          index, authorizer = dependencies
+          yield index, authorizer
+        rescue Ace::Lab::InvalidConfigurationError => e
+          Models::QueryResult.failure("invalid_configuration", e.message)
+        end
+
+        # Dependencies are derived fresh for EVERY query: nothing is
+        # memoized, so revoking deployment grants revokes access on the next
+        # query even for a reused service instance (review round 6, F1).
+        def dependencies
+          return [@loader.load, @authorizer] if @loader
+
+          config = @config || Ace::Lab.config
+          normalized = Atoms::TopologySchema.normalize!(config)
+          grants = if @config
+            # Explicitly injected configuration is a trusted in-process
+            # input (API use and fixtures)
+            normalized["authorization"]["principals"]
+          else
+            # Cascade path: grants come only from the trusted deployment-
+            # controlled document, re-read and re-verified per query; cascade
+            # tiers can never define or expand authorization (review round 4, F3)
+            Molecules::GrantResolver.resolve(
+              documents: Ace::Lab.cascade_documents,
+              topology: normalized["topology"],
+              trusted_path: Ace::Lab.authorization_path
+            )["principals"]
+          end
+
+          loader = Molecules::TopologyLoader.new(normalized)
+          authorizer = Molecules::CallerAuthorizer.new(principals: grants)
+          [loader.load, authorizer]
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    VERSION = "0.1.0"
+  end
+end

data/lib/ace/lab.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "lab/version"
+require "ace/support/config"
+
+module Ace
+  module Lab
+    class Error < StandardError; end
+
+    # Raised when topology configuration violates the schema contract
+    class InvalidConfigurationError < Error; end
+  end
+end
+
+# Load all ace-lab components
+require_relative "lab/atoms/topology_schema"
+require_relative "lab/atoms/binding_freshness"
+require_relative "lab/atoms/public_projection"
+require_relative "lab/models/runtime_binding"
+require_relative "lab/models/topology_entry"
+require_relative "lab/models/query_result"
+require_relative "lab/molecules/topology_loader"
+require_relative "lab/molecules/caller_authorizer"
+require_relative "lab/molecules/grant_resolver"
+require_relative "lab/molecules/inventory_query"
+require_relative "lab/molecules/exact_resolver"
+require_relative "lab/molecules/capability_router"
+require_relative "lab/organisms/topology_service"
+require_relative "lab/cli"
+
+module Ace
+  module Lab
+    # Returns the gem root directory
+    # @return [String] Path to the gem root directory
+    def self.gem_root
+      @gem_root ||= Gem.loaded_specs["ace-lab"]&.gem_dir ||
+        File.expand_path("../..", __dir__)
+    end
+
+    # Check if debug mode is enabled
+    # @return [Boolean]
+    def self.debug?
+      ENV["ACE_DEBUG"] == "1" || ENV["DEBUG"] == "1"
+    end
+
+    # Load ace-lab configuration using the ADR-022 cascade.
+    # Deployed topology lives in .ace/lab/config.yml (project) or
+    # ~/.ace/lab/config.yml (user); gem defaults are an empty, safe topology.
+    # Deliberately NOT memoized: binding facts (attestations) change on disk,
+    # and a long-lived consumer must never keep serving replaced bindings
+    # from a cached document (review round 7, F1). Cascade reads are small.
+    # @return [Hash] Merged configuration hash with defaults
+    def self.config
+      load_config
+    end
+
+    # Same discovery the cascade resolver performs for this namespace
+    LAB_FILE_PATTERNS = ["lab/config.yml", "lab/config.yaml"].freeze
+
+    # Authorization grants live in a single deployment-controlled file at a
+    # FIXED path — never in the caller-writable configuration cascade and
+    # never at a caller-selected location (review rounds 4-5, F3/F1). The
+    # file must be root-owned and not group/world-writable, including every
+    # directory on its real path; GrantResolver verifies and fails closed.
+    AUTHORIZATION_PATH = "/etc/lab/ace-lab/authorization.yml"
+
+    # Path of the trusted authorization grants document. A method (not a
+    # bare constant reference) so tests can stub the seam without any
+    # caller-controllable production override.
+    # @return [String]
+    def self.authorization_path
+      AUTHORIZATION_PATH
+    end
+
+    # Load configuration using Ace::Support::Config cascade.
+    # Load failures raise InvalidConfigurationError (classified by the query
+    # boundary) — silently falling back to empty defaults would misreport
+    # broken deployed configuration as an authorization denial (review R4).
+    # @return [Hash] Merged configuration
+    # @raise [Ace::Lab::InvalidConfigurationError]
+    def self.load_config
+      cascade_documents
+
+      resolver = Ace::Support::Config.create(
+        config_dir: ".ace",
+        defaults_dir: ".ace-defaults",
+        gem_path: gem_root
+      )
+
+      resolver.resolve_namespace("lab").data
+    rescue Ace::Lab::InvalidConfigurationError
+      raise
+    rescue => e
+      # Fixed diagnostic only: the underlying exception message may quote
+      # configuration content, which must never surface pre-authorization
+      # (review round 3, F2)
+      raise InvalidConfigurationError, "invalid lab configuration: could not load deployed configuration (#{e.class})"
+    end
+    private_class_method :load_config
+
+    # The individual cascade documents for this namespace, same discovery the
+    # resolver performs, each validated before use. Cascade merging treats a
+    # non-mapping document as an empty overlay, so a malformed root (e.g. a
+    # YAML array) would be silently ignored (review round 3, F1). Messages
+    # carry the file path — never parsed content.
+    #
+    # Exposed because authorization grants need per-tier documents: a
+    # caller-writable tier must never be able to EXPAND grants (review
+    # round 4, F3), which the merged view cannot express.
+    #
+    # @return [Array<Hash>] {path:, document:, defaults:}
+    def self.cascade_documents
+      finder = Ace::Support::Config::Molecules::ConfigFinder.new(
+        config_dir: ".ace",
+        defaults_dir: ".ace-defaults",
+        gem_path: gem_root,
+        file_patterns: LAB_FILE_PATTERNS
+      )
+
+      finder.find_all.select(&:exists).map do |cascade_path|
+        path = cascade_path.path
+        document = begin
+          require "yaml"
+          YAML.safe_load_file(path, permitted_classes: [Date], aliases: true)
+        rescue
+          raise InvalidConfigurationError, "invalid lab configuration: #{path} could not be parsed as YAML"
+        end
+        unless document.nil? || document.is_a?(Hash)
+          raise InvalidConfigurationError, "invalid lab configuration: #{path} must contain a YAML mapping"
+        end
+
+        {path: path, document: document || {}, defaults: path.start_with?(gem_root)}
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,203 @@
+--- !ruby/object:Gem::Specification
+name: ace-lab
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 2026-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: ace-support-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.31'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.31'
+- !ruby/object:Gem::Dependency
+  name: ace-support-config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: ace-support-test-helpers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Read-only topology registry and capability router. Resolves stable project,
+  agent, and service IDs from ADR-022 configuration without invoking Lab, reading
+  credentials, tracking work, or guessing transient pane/session identifiers.
+email:
+- mc@cs3b.com
+executables:
+- ace-lab
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ace-defaults/lab/config.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- docs/usage.md
+- exe/ace-lab
+- lib/ace/lab.rb
+- lib/ace/lab/atoms/binding_freshness.rb
+- lib/ace/lab/atoms/public_projection.rb
+- lib/ace/lab/atoms/topology_schema.rb
+- lib/ace/lab/cli.rb
+- lib/ace/lab/cli/commands/agents.rb
+- lib/ace/lab/cli/commands/projects.rb
+- lib/ace/lab/cli/commands/resolve.rb
+- lib/ace/lab/cli/commands/route.rb
+- lib/ace/lab/cli/commands/services.rb
+- lib/ace/lab/cli/commands/support.rb
+- lib/ace/lab/models/query_result.rb
+- lib/ace/lab/models/runtime_binding.rb
+- lib/ace/lab/models/topology_entry.rb
+- lib/ace/lab/molecules/caller_authorizer.rb
+- lib/ace/lab/molecules/capability_router.rb
+- lib/ace/lab/molecules/exact_resolver.rb
+- lib/ace/lab/molecules/grant_resolver.rb
+- lib/ace/lab/molecules/inventory_query.rb
+- lib/ace/lab/molecules/topology_loader.rb
+- lib/ace/lab/organisms/topology_service.rb
+- lib/ace/lab/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-lab/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-lab/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Topology and routing CLI for the Lab: address projects, agents, and services
+  by stable IDs'
+test_files: []