ace-lab 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 54eee52265f20d22376fcdf7ac0a748be0c8ec5d7400259310a1a5a37d2f373e
+  data.tar.gz: e9b3746081e8790a2764f8dcbbd54650ddb3a23890cdb653c689c5a5d6ad7d5c
+SHA512:
+  metadata.gz: 78d706d9b60416afdd98a12bbf98dfe90a12e2cd4105c29f3bab5b177dcdea70f8ac0753e35926107790afbdd1fc03c9e792b9c4fd85a45b1dac716122032060
+  data.tar.gz: 646f3f2fae98bc011fabf589a1175c6248f36cd4cd89a7dc2172e0010287affbb16bebe4dc33ce8af5b53e263d2743d1af7c4410c2a307c0e08b215a57aad18f

data/.ace-defaults/lab/config.yml

@@ -0,0 +1,41 @@
+# ace-lab default configuration
+# Override in ~/.ace/lab/config.yml or .ace/lab/config.yml
+#
+# Deployed topology values are owned by the lab-config repository; this
+# default ships a deliberately empty, safe structure so a fresh install
+# resolves to "no topology" instead of guessed values.
+#
+# AUTHORIZATION GRANTS DO NOT LIVE HERE. Caller-writable cascade documents
+# must never define who may see what (review round 4, F3). Grants come from
+# the single deployment-controlled file /etc/lab/ace-lab/authorization.yml —
+# a fixed path; the file and every directory on its real path must be
+# root-owned and not group/world-writable, or queries fail closed:
+#
+#   { "principals": { "<verified-local-uid>": { "projects": ["project-id"] } } }
+#
+# Topology schema (version 1):
+#   topology:
+#     projects:
+#       - { id: project-id, label: Display name }
+#     agents:
+#       - id: agent-id
+#         project: project-id
+#         role: planner
+#         capabilities: ["planning"]
+#         binding: { kind: runtime, state: active, instance_id: iid,
+#                    attested_instance_id: iid }
+#     services:
+#       - id: service-id
+#         project: project-id
+#         capabilities: ["search"]
+#         default_for: ["search"]
+#         endpoint: { kind: http, url: "https://service.example/internal" }
+#         binding: { kind: service, state: active, instance_id: iid,
+#                    attested_instance_id: iid }
+
+schema_version: 1
+
+topology:
+  projects: []
+  agents: []
+  services: []

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-28
+
+### Added
+
+- Topology/routing CLI (`ace-lab`) addressing projects, agents, and services by
+  stable IDs: `projects`, `agents`, `services`, `resolve`, `route` commands with
+  deterministic JSON output (`--format json`).
+- ADR-022 configuration contract for Lab topology (`schema_version: 1`) with
+  validated stable IDs, project references, capability normalization, binding
+  attestation fields, and verified-local-principal authorization mapping.
+- Classified query outcomes: `missing`, `ambiguous`, `stale`, `unauthorized`,
+  `invalid_configuration`.
+- Allowlist-based public projection; tokens, auth-file paths, endpoint
+  credentials, URL userinfo, query parameters, fragments, and raw pane/session
+  identifiers never appear in public output.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+## ace-lab
+
+Topology and routing CLI for the Lab: address projects, agents, and services
+by stable IDs. Part of ACE (Agentic Coding Environment).
+
+`ace-lab` answers one question -- *what is the stable ID of the project, agent,
+or service I mean, and what is it authorized and able to do?* -- from
+configuration alone. It never invokes Lab, never reads credentials, tracks no
+work, and never guesses transient pane or session identifiers.
+
+### Install
+
+    gem install ace-lab
+
+### Usage
+
+Configure topology via the ADR-022 cascade (`~/.ace/lab/config.yml` or
+`.ace/lab/config.yml`; deployed values are owned by the `lab-config`
+repository). Authorization grants live in a separate deployment-controlled
+file at the fixed path `/etc/lab/ace-lab/authorization.yml` — root-owned and
+not group/world-writable, verified at every query — never in the
+caller-writable cascade and never at a caller-selected location:
+
+```yaml
+# .ace/lab/config.yml — topology only
+schema_version: 1
+topology:
+  projects:
+    - { id: atlas, label: Atlas platform }
+  agents:
+    - id: atlas-planner
+      project: atlas
+      role: planner
+      capabilities: [planning]
+      binding: { kind: runtime, state: active, instance_id: i1, attested_instance_id: i1 }
+  services:
+    - id: atlas-search
+      project: atlas
+      capabilities: [search]
+      default_for: [search]
+      endpoint: { kind: http, url: "https://search.example.internal/query?token=secret" }
+      binding: { kind: service, state: active, instance_id: i2, attested_instance_id: i2 }
+```
+
+```yaml
+# trusted grants file (deployment-owned)
+principals:
+  "<verified-local-uid>": { projects: ["atlas"] }
+```
+
+Query it:
+
+    ace-lab projects --format json
+    ace-lab agents --project atlas --format json
+    ace-lab services --project atlas --format json
+    ace-lab resolve --id atlas-planner --format json
+    ace-lab route --project atlas --capability search --format json
+
+Every command prints one deterministic JSON document:
+
+    {"status":"ok","data":{"entry":{"id":"atlas-search","project":"atlas",
+     "capabilities":["search"],"default_for":["search"],
+     "binding":{"kind":"service","state":"available",
+     "endpoint":{"kind":"http","url":"https://search.example.internal"}}}}}
+
+Failures are classified: `missing`, `ambiguous`, `stale`, `unauthorized`,
+`invalid_configuration` -- for example a replaced agent process:
+
+    {"status":"error","error":{"code":"stale","message":"stable ID
+     \"atlas-planner\" has a stale runtime binding; ...","id":"atlas-planner",
+     "project":"atlas"}}
+
+### Guarantees
+
+- **Stable IDs are canonical.** Labels are display values and never resolve.
+
+  Exact match or a classified `missing` error.
+
+- **Public output never leaks.** Tokens, auth-file paths, endpoint userinfo,
+
+  query parameters, fragments, pane/session identifiers, and instance
+  identities are excluded by an allowlist projection, not field redaction.
+
+- **Authorization comes from the verified local process owner**, matched
+
+  against configured principals. There is no `--role` or `--principal` flag;
+  identity flags are rejected outright.
+
+- **Routing is project-local.** Candidates are capable services of the
+
+  requested project with fresh (active + attested) bindings. Zero candidates
+  are `missing`; several equal candidates need a configured `default_for`, or
+  the result is `ambiguous`. Another project's service is never picked.
+
+- **Read-only by contract.** No Lab invocation, no execution state, no
+
+  scheduling, no credentials -- service invocation and execution state belong
+  to separate tools.
+
+### Non-goals
+
+`ace-lab` is not an execution-state engine. It does not invoke services
+(`8wr.t.qjx` owns the service contract), track Works or assignment state, or
+schedule anything. Deployed topology values are owned by `lab-config`
+(`8wl.t.gad`); this package defines and validates the schema.
+
+### Development
+
+    bundle install
+    ace-test ace-lab        # or: bundle exec rake test from ace-lab/

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/usage.md

@@ -0,0 +1,178 @@
+# ace-lab usage
+
+Topology and routing CLI for the Lab. Resolves stable project, agent, and
+service IDs from configuration -- without knowing transient pane IDs or
+holding service credentials.
+
+## Commands
+
+All commands accept `--format json` (the only supported format; anything else
+is rejected) and `-q/--quiet` (suppress stdout; exit semantics unchanged).
+
+### `ace-lab projects`
+
+List projects visible to the verified caller.
+
+    $ ace-lab projects --format json
+    {"status":"ok","data":{"projects":[{"id":"atlas","label":"Atlas platform"},{"id":"borealis"}]}}
+
+A caller with no configured principal receives:
+
+    {"status":"error","error":{"code":"unauthorized","message":"caller has no configured authorization for any lab project"}}
+
+### `ace-lab agents --project PROJECT`
+
+List agents in one project.
+
+    $ ace-lab agents --project atlas --format json
+    {"status":"ok","data":{"agents":[{"id":"atlas-planner","project":"atlas","role":"planner","capabilities":["planning"],"binding":{"kind":"runtime","state":"available"}}]}}
+
+`binding.state` is `available` when the configured runtime binding is active
+and its instance identity matches the attestation; otherwise `stale`.
+
+### `ace-lab services --project PROJECT`
+
+List services in one project.
+
+    $ ace-lab services --project atlas --format json
+    {"status":"ok","data":{"services":[{"id":"atlas-search","project":"atlas","capabilities":["search"],"default_for":["search"],"binding":{"kind":"service","state":"available","endpoint":{"kind":"http","url":"https://search.example.internal:8443"}}}]}}
+
+The endpoint is a sanitized identity: scheme, host, and explicit port only.
+
+### `ace-lab resolve --id ID`
+
+Resolve one entry by exact stable ID.
+
+    $ ace-lab resolve --id atlas-planner --format json
+    {"status":"ok","data":{"entry":{"id":"atlas-planner","project":"atlas","role":"planner","capabilities":["planning"],"binding":{"kind":"runtime","state":"available"}}}}
+
+Labels are display values and never resolve: `resolve "Atlas platform"` is a
+`missing` error.
+
+### `ace-lab route --project PROJECT --capability CAPABILITY`
+
+Select a configured capable service in the requested project.
+
+    $ ace-lab route --project atlas --capability search --format json
+    {"status":"ok","data":{"entry":{"id":"atlas-search","project":"atlas","capabilities":["search"],"default_for":["search"],"binding":{"kind":"service","state":"available","endpoint":{"kind":"http","url":"https://search.example.internal:8443"}}}}}
+
+Routing never invokes the service and never grants credentials.
+
+## Error semantics
+
+Errors are one deterministic JSON document on stdout plus a non-zero exit.
+
+| Code | Meaning |
+|------|---------|
+| `missing` | No entry with that stable ID, or no capable service in the project |
+| `ambiguous` | Several equally capable services without a configured `default_for` |
+| `stale` | Binding is inactive, unattested, or the instance identity was replaced |
+| `unauthorized` | Caller's verified local identity has no principal for the project |
+| `invalid_configuration` | Topology config violates the schema; message is actionable |
+
+Example:
+
+    $ ace-lab resolve --id atlas-coder --format json; echo $?
+    {"status":"error","error":{"code":"stale","message":"stable ID \"atlas-coder\" has a stale runtime binding; a replaced process must re-attest before routing","id":"atlas-coder","project":"atlas"}}
+    1
+
+## Configuration
+
+Schema version 1, resolved through the ADR-022 cascade (project `.ace/lab/`
+over user `~/.ace/lab/` over gem defaults; gem defaults are an empty, safe
+topology). Cascade documents carry **topology only**:
+
+```yaml
+schema_version: 1
+topology:
+  projects:
+    - id: atlas               # globally unique across all entries
+      label: Display name     # display only; never resolves
+  agents:
+    - id: atlas-planner
+      project: atlas          # must reference an existing project
+      role: planner
+      capabilities: [planning]  # non-empty; normalized (stripped, lowercased)
+      binding:
+        kind: runtime           # agents bind to runtimes, services to services
+        state: active           # routeable only when active
+        instance_id: i1         # runtime identity fact
+        attested_instance_id: i1  # must equal instance_id to be fresh
+  services:
+    - id: atlas-search
+      project: atlas
+      capabilities: [search]
+      default_for: [search]     # exactly one default may win among candidates
+      endpoint:
+        kind: http              # http or https
+        url: "https://search.example.internal/query?token=secret"  # stored, never published
+      binding: { kind: service, state: active, instance_id: i2, attested_instance_id: i2 }
+```
+
+### Authorization grants
+
+Grants never live in the cascade: project and user documents are
+caller-writable, so an `authorization` section there is rejected as
+`invalid_configuration`. Grants come from a single deployment-controlled
+file at the **fixed path** `/etc/lab/ace-lab/authorization.yml` (installed
+by the `lab-config` deployment). The location is not caller-selectable —
+there is no flag or environment override. At every query the tool verifies
+the file and every directory on its real path are root-owned and not
+group/world-writable, and opens the file `O_NOFOLLOW`; any failed
+verification fails closed:
+
+```yaml
+principals:
+  "<verified-local-uid>":     # passwd username or numeric uid of the caller
+    projects: ["atlas"]
+```
+
+The grants file is machine-global: it is validated structurally only, so a
+principal may reference projects absent from the current directory's
+topology. Such grants are valid but never match a locally configured
+project. All-digit principal keys are matched as uids only — an all-digit
+passwd username is authorized solely through its uid, so it can never
+consume a different account's numeric-uid grant.
+
+A missing trusted file means nobody is authorized (fail closed).
+
+Validation of the topology cascade rejects duplicate IDs (globally unique
+across projects, agents, services), unknown project references, malformed
+capabilities, defaults for undeclared capabilities, unusable endpoints
+(absolute http(s) URL with a host and a port in 1–65535; `endpoint.kind` is
+`http` or `https`), unsupported binding kinds, and principals referencing
+unknown projects.
+
+**Error messages are value-free by design:** validation runs before
+authorization, so messages use positional field locations
+(`topology.agents[0].project references an unknown project`) and never echo
+configured IDs, project names, or principal names — configuration defects
+cannot disclose topology to unauthorized callers.
+
+**Ownership:** deployed topology and authorization values are maintained by
+the `lab-config` repository (`8wl.t.gad`). `ace-lab` defines the schema and
+reads; it never provisions.
+
+## Guarantees and boundaries
+
+- Public output is built from a strict allowlist: `id`, `project`, `label`,
+
+  `role`, `capabilities`, `default_for`, binding `kind` + availability state,
+  and a sanitized endpoint identity. Tokens, auth-file paths, URL userinfo,
+  paths, query parameters, fragments, pane/session IDs, and instance
+  identities never appear in any command output.
+
+- Caller identity comes from the verified local process owner
+
+  (username or uid). `--role`, `--principal`, and `--caller` flags are
+  rejected: authorization is a property of the caller, not an input.
+
+- A replaced process keeps its stable ID; until re-attested, queries
+
+  classify it `stale` -- an explicit unavailable result, never a routeable
+  answer.
+
+- No Works, assignment state, or scheduling. Service invocation belongs to
+
+  `8wr.t.qjx`; execution state to `8wr.t.qjl`. The Lab execution binary
+  (`/usr/local/bin/lab`) is never invoked or required.

data/exe/ace-lab

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ace/lab"
+
+# No args -> show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start CLI with exception-based exit code handling (per ADR-023).
+# No bundler/setup here: an installed gem must run without a Gemfile;
+# use `bundle exec` in development to resolve workspace sources.
+begin
+  exit_code = Ace::Lab::CLI.start(args)
+  exit(exit_code) if exit_code.is_a?(Integer) && exit_code.nonzero?
+rescue Ace::Support::Cli::Error => e
+  # e.to_s carries the documented "Error: " prefix (Ace::Support::Cli::Error)
+  warn e.to_s # standard:disable Lint/RedundantStringCoercion
+  exit(e.exit_code)
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Atoms
+      # Pure freshness classification for a runtime binding (spec 8wq.t.1w4).
+      # A binding is fresh only when it is explicitly active AND the configured
+      # instance identity exactly matches its attestation. Absent, inactive,
+      # or mismatched identities classify as stale — never guessed fresh.
+      module BindingFreshness
+        FRESH = "fresh"
+        STALE = "stale"
+
+        class << self
+          # @param binding [Ace::Lab::Models::RuntimeBinding, nil]
+          # @return [String] FRESH or STALE
+          def classify(binding)
+            return STALE if binding.nil?
+            return STALE unless binding.state == "active"
+            return STALE if binding.instance_id.nil? || binding.instance_id.empty?
+            return STALE unless binding.instance_id == binding.attested_instance_id
+
+            FRESH
+          end
+
+          def fresh?(binding)
+            classify(binding) == FRESH
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ace
+  module Lab
+    module Atoms
+      # Allowlist-based public projection of topology entries (spec 8wq.t.1w4).
+      # Public output is constructed exclusively from the fields below, so raw
+      # configuration values can never leak: no tokens, auth-file paths,
+      # endpoint credentials, URL userinfo, path, query parameters, fragments,
+      # pane/session identifiers, or instance identities.
+      module PublicProjection
+        class << self
+          # @return [Hash] {id, label?}
+          def project(entry)
+            public_entry = {"id" => entry.id}
+            public_entry["label"] = entry.label if entry.label
+            public_entry
+          end
+
+          # @return [Hash] {id, project, label?, role, capabilities,
+          #                 binding: {kind, state}}
+          def agent(entry)
+            public_entry = {
+              "id" => entry.id,
+              "project" => entry.project,
+              "role" => entry.role,
+              "capabilities" => entry.capabilities,
+              "binding" => binding_summary(entry.binding)
+            }
+            public_entry["label"] = entry.label if entry.label
+            public_entry
+          end
+
+          # @return [Hash] {id, project, label?, capabilities, default_for,
+          #                 binding: {kind, state, endpoint: {kind, url?}}}
+          def service(entry)
+            public_entry = {
+              "id" => entry.id,
+              "project" => entry.project,
+              "capabilities" => entry.capabilities,
+              "default_for" => entry.default_for,
+              "binding" => binding_summary(entry.binding).merge(endpoint_summary(entry))
+            }
+            public_entry["label"] = entry.label if entry.label
+            public_entry
+          end
+
+          # Project an entry of any kind
+          def entry(entry)
+            case entry.kind
+            when "project" then project(entry)
+            when "agent" then agent(entry)
+            else service(entry)
+            end
+          end
+
+          private
+
+          # Availability state derived from freshness; never exposes
+          # instance identities or raw configured state
+          def binding_summary(binding)
+            {
+              "kind" => binding&.kind,
+              "state" => binding_freshness(binding)
+            }
+          end
+
+          def binding_freshness(binding)
+            fresh = Ace::Lab::Atoms::BindingFreshness.fresh?(binding)
+            fresh ? "available" : "stale"
+          end
+
+          # Safe endpoint identity: scheme, host, and explicit port only.
+          # Userinfo, path, query, and fragment are dropped by construction;
+          # an unparseable URL projects no endpoint identity at all.
+          def endpoint_summary(entry)
+            endpoint = entry.endpoint
+            return {} unless endpoint.is_a?(Hash)
+
+            {"endpoint" => {"kind" => endpoint["kind"], "url" => sanitize_url(endpoint["url"])}}
+          end
+
+          def sanitize_url(url)
+            uri = URI.parse(url)
+            return nil unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+            return nil if uri.host.nil? || uri.host.empty?
+
+            (uri.port == uri.default_port) ? "#{uri.scheme}://#{uri.host}" : "#{uri.scheme}://#{uri.host}:#{uri.port}"
+          rescue URI::Error, ArgumentError
+            nil
+          end
+        end
+      end
+    end
+  end
+end