feat: unified naming convention phases 1-3 (v3.0 AMQP + API)

[Esity]

Summary

Implements Phases 1-3 of the unified naming convention across the LegionIO framework. This is the breaking-change boundary for v3.0 AMQP topology and API routing.

Phase 1: Definition DSL + Component DSL Standardization (no breaking changes)

• Legion::Extensions::Definitions mixin: definition DSL for method contracts (desc, inputs, outputs, remote_invocable, mcp_exposed, idempotent, risk_tier, tags, requires). Defaults: remote_invocable: true, mcp_exposed: true, idempotent: false, risk_tier: :standard
• Legion::Extensions::Actors::Dsl mixin: define_dsl_accessor for inheritable class-level DSL on all actor types
• Builders::Runners auto-extends Definitions onto every discovered runner module
• Absorbers::Base#absorb as canonical entry point (alias handle absorb for backward compat)

Phase 2: API Router Standardization

• Three-tier Legion::API::Router with register_library_routes and register_extension_routes
• /api/extensions/{lex}/{runner}/{function} dispatch via LexDispatch.build_envelope (propagates X-Legion-Task-Id, X-Legion-Conversation-Id, X-Legion-Parent-Id, X-Legion-Master-Id, X-Legion-Chain-Id, X-Legion-Debug headers)

Phase 3: AMQP Topology Rename (breaking — v2.0 → v3.0)

• amqp_prefix changed from legion.{lex_name} to lex.{lex_name} for all extension exchanges and queues
• Queue routing keys now include component type segment: runners.{runner_name} (short-form) and lex.{lex_name}.runners.{runner_name}.# (fully-qualified)
• generate_messages_from_definitions in Core#autobuild: auto-creates Legion::Transport::Message subclasses for each runner method with a definition, using lex.{lex_name}.runners.{runner_name}.{method} routing key
• legion admin purge-topology CLI: enumerates/deletes legacy legion.{lex}.* exchanges and queues via RabbitMQ management API; dry-run by default, --execute to delete

Test Plan

• bundle exec rspec — 3853 examples, 0 failures (verified)
• bundle exec rubocop — 706 files, 0 offenses (verified)
• Verify legion admin purge-topology --help lists all options
• Verify amqp_prefix returns lex.{lex_name} for an extension
• Verify queue routing keys include runners.{runner_name} segment
• Verify legacy topology is correctly identified by pattern matching in specs

Migration

Existing RabbitMQ deployments will have stale legion.{lex_name}.* exchanges and queues after this upgrade. Run:

legion admin purge-topology --execute

See docs/protocol/LEGION_WIRE_PROTOCOL.md (updated in companion PR) for the full migration table.

[Copilot]

Pull request overview

This PR introduces a broad set of v3.0 framework updates, including new CLI chat tooling, expanded REST/GraphQL API surface, infrastructure/deployment assets, and dependency/runtime upgrades aligned with the “unified naming convention” milestone.

Changes:

• Adds a large set of CLI Chat “tools” (RubyLLM-based), registries/loaders, and supporting utilities (permissions, checkpointing, session storage, subagents).
• Adds multiple new API routes/middleware (auth token exchange, governance, costs, traces, capacity, catalog, hooks, transport, settings, webhooks, SSE events) plus GraphQL schema/types/resolvers.
• Updates packaging/runtime/deployment: Ruby 3.4+, gemspec dependencies, new Dockerfile, Helm chart, TLS config assets, and GitHub workflows.

Reviewed changes

Copilot reviewed 167 out of 771 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
lib/legion/cli/chat/tools/list_extensions.rb	Adds chat tool to query extensions via HTTP API.
lib/legion/cli/chat/tools/knowledge_stats.rb	Adds chat tool to fetch Apollo stats via HTTP API.
lib/legion/cli/chat/tools/knowledge_maintenance.rb	Adds chat tool to run Apollo maintenance via HTTP POST.
lib/legion/cli/chat/tools/ingest_knowledge.rb	Adds chat tool to ingest knowledge into Apollo.
lib/legion/cli/chat/tools/escalation_status.rb	Adds chat tool to report LLM escalation tracking.
lib/legion/cli/chat/tools/entity_extract.rb	Adds chat tool for Apollo entity extraction runner.
lib/legion/cli/chat/tools/edit_file.rb	Adds file editing tool with checkpointing.
lib/legion/cli/chat/tools/detect_anomalies.rb	Adds chat tool to call anomaly detection API endpoint.
lib/legion/cli/chat/tools/consolidate_memory.rb	Adds memory consolidation tool using LLM summarization.
lib/legion/cli/chat/tools/budget_status.rb	Adds local budget/cost-status tool (no daemon required).
lib/legion/cli/chat/tools/arbitrage_status.rb	Adds tool to report arbitrage/pricing selection status.
lib/legion/cli/chat/tool_registry.rb	Registers built-in tools and dynamically discovers extension tools.
lib/legion/cli/chat/team.rb	Adds per-thread “current user” context helper.
lib/legion/cli/chat/subagent.rb	Adds concurrent headless subagent runner using threads + Open3.
lib/legion/cli/chat/status_indicator.rb	Adds spinner UI driven by session events.
lib/legion/cli/chat/session_store.rb	Adds on-disk save/load/list/restore for chat sessions.
lib/legion/cli/chat/session.rb	Adds session wrapper with event callbacks + budget guard.
lib/legion/cli/chat/progress_bar.rb	Adds CLI progress bar utility.
lib/legion/cli/chat/permissions.rb	Adds interactive/auto gating for tool execution by permission tier.
lib/legion/cli/chat/memory_store.rb	Adds simple markdown-backed memory store (project/global).
lib/legion/cli/chat/markdown_renderer.rb	Adds ANSI markdown renderer w/ Rouge highlighting fallback.
lib/legion/cli/chat/extension_tool_loader.rb	Loads RubyLLM tools shipped inside extensions with tier overrides.
lib/legion/cli/chat/extension_tool.rb	Adds mixin for extension tools to declare permission tiers.
lib/legion/cli/chat/checkpoint.rb	Adds rollback/checkpoint support for file modifications.
lib/legion/cli/chat/chat_logger.rb	Adds rotating file logger for chat.
lib/legion/cli/chat/agent_registry.rb	Adds agent config discovery (JSON/YAML) from .legion/agents.
lib/legion/cli/chat/agent_delegator.rb	Routes @agent and /agent invocations to subagents.
lib/legion/cli/chain_command.rb	Adds Thor-based chain CLI for listing/creating/deleting chains.
lib/legion/cli/chain.rb	Adds frozen string literal magic comment.
lib/legion/cli/acp_command.rb	Adds CLI entry for ACP agent (stdio).
lib/legion/cli/absorb_command.rb	Adds CLI entry for absorber dispatch and pattern listing/resolve.
lib/legion/chat/skills.rb	Adds discovery/parser for skills markdown with YAML frontmatter.
lib/legion/chat/notification_queue.rb	Adds thread-safe priority queue for notifications.
lib/legion/chat/notification_bridge.rb	Bridges Legion events → notification queue w/ pattern priority mapping.
lib/legion/catalog.rb	Adds client to register tools/workers to external catalog via HTTP.
lib/legion/capacity/model.rb	Adds capacity aggregation/forecast model for workers.
lib/legion/audit/siem_export.rb	Adds export helpers for SIEM-friendly payloads.
lib/legion/audit/hash_chain.rb	Adds hash chain compute/verify helpers for audit integrity.
lib/legion/audit/cold_storage.rb	Adds cold storage abstraction (local / S3).
lib/legion/audit/archiver_actor.rb	Adds scheduled archival actor wrapper with cron field parsing.
lib/legion/audit.rb	Adds audit event recording + query helpers.
lib/legion/api/workflow.rb	Adds relationship graph route backed by graph builder.
lib/legion/api/webhooks.rb	Adds basic CRUD routes for webhook registration.
lib/legion/api/validators.rb	Adds request validation helper methods (required, enum, uuid, int bounds).
lib/legion/api/transport.rb	Adds transport status/discovery/publish endpoints.
lib/legion/api/traces.rb	Adds trace search/summary/anomalies/trend routes.
lib/legion/api/token.rb	Adds JWT issuing helpers for worker/human tokens.
lib/legion/api/tenants.rb	Adds tenant management/quota endpoints.
lib/legion/api/tasks.rb	Adds task collection/member/log endpoints plus API-based task creation.
lib/legion/api/settings.rb	Adds API access to settings with redaction and write restrictions.
lib/legion/api/schedules.rb	Adds scheduler CRUD endpoints and logs endpoint.
lib/legion/api/router.rb	Adds route registry/router abstraction for infra/library/extension routes.
lib/legion/api/relationships.rb	Adds CRUD endpoints for relationships.
lib/legion/api/prompts.rb	Adds prompt list/show/run endpoints via lex-prompt client + LLM.
lib/legion/api/org_chart.rb	Adds org-chart endpoint combining extensions/functions/workers.
lib/legion/api/nodes.rb	Adds node list/show endpoints.
lib/legion/api/middleware/tenant.rb	Adds middleware to resolve/attach tenant context to requests.
lib/legion/api/middleware/request_logger.rb	Adds API request timing logger middleware.
lib/legion/api/middleware/body_limit.rb	Adds request size limit middleware.
lib/legion/api/middleware/api_version.rb	Adds v1 rewrite + deprecation headers for unversioned APIs.
lib/legion/api/metrics.rb	Adds Prometheus metrics endpoint.
lib/legion/api/lex.rb	Adds LEX route listing + dispatch endpoint.
lib/legion/api/hooks.rb	Adds hooks registry listing + verification + dispatch handler endpoints.
lib/legion/api/graphql/types/worker_type.rb	Adds GraphQL Worker type.
lib/legion/api/graphql/types/task_type.rb	Adds GraphQL Task type.
lib/legion/api/graphql/types/query_type.rb	Adds GraphQL root query and resolver mapping.
lib/legion/api/graphql/types/node_type.rb	Adds GraphQL Node type.
lib/legion/api/graphql/types/extension_type.rb	Adds GraphQL Extension type.
lib/legion/api/graphql/types/base_object.rb	Adds GraphQL BaseObject.
lib/legion/api/graphql/schema.rb	Adds GraphQL schema config (depth/complexity).
lib/legion/api/graphql/resolvers/workers.rb	Adds worker resolvers from data or registry fallback.
lib/legion/api/graphql/resolvers/tasks.rb	Adds task resolvers from data.
lib/legion/api/graphql/resolvers/node.rb	Adds node resolver.
lib/legion/api/graphql/resolvers/extensions.rb	Adds extension resolvers from data or registry fallback.
lib/legion/api/graphql.rb	Adds GraphQL endpoint + GraphiQL HTML.
lib/legion/api/governance.rb	Adds governance approvals endpoints backed by lex-audit runner.
lib/legion/api/gaia.rb	Adds Gaia status/channels/buffer/sessions and Teams webhook ingest.
lib/legion/api/extensions.rb	Adds extension/runner/function listing and invoke route.
lib/legion/api/events.rb	Adds SSE streaming + recent events buffer endpoint.
lib/legion/api/costs.rb	Adds metering cost summary and breakdown endpoints.
lib/legion/api/coldstart.rb	Adds coldstart ingest endpoint for file/dir ingestion.
lib/legion/api/codegen.rb	Adds codegen status/generated/gaps/cycle endpoints.
lib/legion/api/chains.rb	Adds chain CRUD endpoints.
lib/legion/api/catalog.rb	Adds extension catalog manifest endpoints.
lib/legion/api/capacity.rb	Adds capacity aggregate/forecast/per-worker endpoints.
lib/legion/api/auth.rb	Adds OAuth token-exchange style endpoint for Entra → Legion tokens.
lib/legion/api/audit.rb	Adds audit listing and verify endpoints.
lib/legion/api/acp.rb	Adds ACP well-known agent card + task create/status endpoints.
lib/legion.rb	Updates boot requires and adds autoloads for Region/Lock/Leader.
legionio.gemspec	Updates metadata, required Ruby, executables, and runtime dependencies.
exe/lex_gen	Removes legacy lex generator executable.
exe/legionio	Replaces legacy daemon/optparse launcher with CLI entry + performance tuning.
exe/legion	Adds interactive TTY default behavior and headless chat for piped stdin.
docs/README.md	Adds “Moved” doc stub referencing local-only docs path.
docker_deploy.rb	Adds frozen string literal comment.
deploy/helm/legion/values.yaml	Adds Helm chart values for api/worker and dependencies.
deploy/helm/legion/templates/serviceaccount.yaml	Adds ServiceAccount template.
deploy/helm/legion/templates/service-api.yaml	Adds API Service template.
deploy/helm/legion/templates/pdb.yaml	Adds PodDisruptionBudget template.
deploy/helm/legion/templates/hpa-worker.yaml	Adds worker HPA template.
deploy/helm/legion/templates/deployment-worker.yaml	Adds worker Deployment template.
deploy/helm/legion/templates/deployment-api.yaml	Adds API Deployment template.
deploy/helm/legion/templates/_helpers.tpl	Adds Helm helper templates for naming/labels.
deploy/helm/legion/Chart.yaml	Adds Helm chart metadata.
config/tls/settings-tls.json	Adds TLS settings example for transport/data/cache/api.
config/tls/generate-certs.sh	Adds local dev certificate generation script.
config/tls/README.md	Adds TLS quick-start docs.
attribution.txt	Removes placeholder attribution file.
SECURITY.md	Removes placeholder security policy file.
NOTICE.txt	Removes notice file with prior attribution.
LICENSE	Updates copyright line.
INDIVIDUAL_CONTRIBUTOR_LICENSE.md	Removes prior CLA text.
Gemfile	Updates dependencies and local path overrides for workspace development.
Dockerfile	Replaces Alpine image with multi-stage Debian slim build/runtime + healthcheck.
CONTRIBUTING.md	Removes prior Optum contribution guidelines.
CODE_OF_CONDUCT.md	Removes prior code of conduct.
CODEOWNERS	Adds CODEOWNERS config.
.rubocop.yml	Updates RuboCop config for Ruby 3.4 and new excludes.
.github/workflows/sourcehawk-scan.yml	Removes Sourcehawk workflow.
.github/workflows/rubocop.yml	Removes legacy RuboCop workflow.
.github/workflows/rspec.yml	Removes legacy RSpec workflow.
.github/workflows/publish-homebrew.yml	Adds release-triggered Homebrew dispatch workflow.
.github/workflows/ci.yml	Adds reusable-workflow-based CI, release, docker publish, etc.
.github/workflows/ci-cd.yml	Adds Helm lint workflow.
.github/workflow-templates/eval-gate.yml	Adds eval-gate workflow template.
.github/dependabot.yml	Adds Dependabot for bundler and GitHub Actions.
.github/CODEOWNERS	Adds org/team-based CODEOWNERS for repo paths.
.dockerignore	Adds docker context excludes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 168 out of 773 changed files in this pull request and generated 11 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 168 out of 773 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This route uses parsed_body, while the rest of the API routes introduced in this PR use parse_request_body. If parsed_body isn’t defined on this Sinatra app, this will raise at runtime; even if it is defined, it’s inconsistent in key type expectations (string keys here vs symbol keys elsewhere). Use the same request parsing helper as the other routes for consistency and to avoid runtime failures.

[Copilot]

When filtering by extension, edges are kept if either endpoint matches, but nodes is filtered to only the matching set. This can yield edges referencing nodes that are no longer present in the nodes list, producing an inconsistent graph response. Either (a) filter edges to those whose source and target are in node_ids, or (b) include the neighboring nodes needed to satisfy the retained edges.

Suggested change

	edges = edges.select { |e| node_ids.include?(e[:source]) || node_ids.include?(e[:target]) }
	edges = edges.select { |e| node_ids.include?(e[:source]) && node_ids.include?(e[:target]) }

[Copilot]

There are two concrete issues in this SSE implementation: (1) the background thread blocks indefinitely on queue.pop even after the client disconnects—out.callback/errback removes the listener but does not stop the thread—leading to leaked threads per connection; and (2) this file treats the Legion::Events.on('*') callback payload as a single event hash, while other new code in this PR (e.g., NotificationBridge) uses (event_name, payload), so one of these is likely incompatible with the actual Events API. Consider: stopping the thread on disconnect (e.g., a closed flag + pushing a sentinel/using timed pop) and aligning the Events.on callback signature/format so event: name and data: payload are reliably produced.

[Copilot]

Concurrency limits are not enforced atomically: spawn checks at_capacity? under the mutex, but then adds to @running later—multiple callers can pass the check concurrently and exceed @max_concurrency. Also, wait_all iterates @running without synchronization while worker threads remove entries, which can lead to inconsistent behavior. Wrap the capacity check + insertion into a single @mutex.synchronize block, and have wait_all iterate over a snapshot captured under the mutex.

[Copilot]

This implementation does an N+1 query for Function.where(extension_id: ext.id) inside the extensions loop, and also re-filters workers for the same extension on every function iteration. To avoid the extra DB round-trips and repeated O(n) scans, fetch/group functions by extension_id once, and pre-group workers by extension_name once, then reuse those groups while building the response.

[Copilot]

Using @entries.length in the backup filename can cause collisions/overwrites when older entries are shifted off due to @max_depth (the length will shrink and previously used prefixes can repeat). Use a monotonically increasing sequence (stored separately), a timestamp, or a UUID for backup filenames to ensure uniqueness.

[Copilot]

The PR title/description focuses on unified naming convention Phases 1–3 (AMQP topology + API routing), but this change set also introduces large new surfaces like GraphQL endpoints (and additionally Helm/Docker/TLS scaffolding in other files). Either update the PR description to reflect these additional deliverables or split the unrelated features into separate PRs to keep the breaking-change boundary and migration scope clear.