legionio 1.4.13 → 1.4.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b61599f64cd23e52b9cbf85631dce4bdb16afeec87b5022229e7ae63f664917
-  data.tar.gz: 339df852d48a4ce9eddc92d1a8fd6c3240bda51f7d91f258352a6bc021aea2f0
+  metadata.gz: b82509c414c56ab775cbaa5879a5312e9d3fd69226eadae308c52f5cba2bff25
+  data.tar.gz: c82590fb0283ee9db793c5b18751dbba8eb51c209351e2674a2ac542e875b718
 SHA512:
-  metadata.gz: bbb574075f5512af6a3783acb5bf02d666cf94eb959ac9827639e3bfb29467b1c97ad0d2d562e8318b173e3eaaf73a1ad2db7aaa29957f1682ffd0076dfaa27d
-  data.tar.gz: 2e4dd37e3f3a7e4520d4b270998a2df0eb1e51accc235061b0974fad27977895e7e29064a6af671b003462815a143081c808fd938e0e4b11eda2823de5416c8d
+  metadata.gz: eff59d6453668b41bfa4047f77db11d02dc3fadacd59801d94fc1a7ec4af14598e30d817e0f075631b087a195e1715a68744a0e399fec728c0d426d8b3dc20e6
+  data.tar.gz: 10f935f6b10a6db5ef4df40e84a487b5fac01a10bc4789a3eca257aed77294a804309eccca224c70b5a3b082de5e0338408464a2dacb1fc353ef43fa54e128fd

data/.rubocop.yml

@@ -35,6 +35,7 @@ Metrics/BlockLength:
     - 'lib/legion/cli/swarm_command.rb'
     - 'lib/legion/cli/gaia_command.rb'
     - 'lib/legion/cli/schedule_command.rb'
+    - 'lib/legion/cli/update_command.rb'
 
 Metrics/AbcSize:
   Max: 60

data/CHANGELOG.md

@@ -1,5 +1,148 @@
 # Legion Changelog
 
+## [1.4.29] - 2026-03-16
+
+### Added
+- `legion init`: one-command workspace setup with environment detection
+- `InitHelpers::EnvironmentDetector`: checks for RabbitMQ, database, Vault, Redis, git, existing config
+- `InitHelpers::ConfigGenerator`: ERB template-based config generation, `.legion/` workspace scaffolding
+- `--local` flag for zero-dependency development mode
+- `--force` flag to overwrite existing config files
+
+## [1.4.28] - 2026-03-16
+
+### Added
+- `Legion::Telemetry` module: opt-in OpenTelemetry tracing with `with_span` wrapper
+- `setup_telemetry` in Service: initializes OTel SDK with OTLP exporter when `telemetry.enabled: true`
+- `sanitize_attributes` helper for safe OTel attribute conversion
+- `record_exception` helper for span error recording
+
+## [1.4.27] - 2026-03-16
+
+### Added
+- `legion update` CLI command: updates all Legion gems (`legionio`, `legion-*`, `lex-*`) using the current Ruby's gem binary
+- `--dry-run` flag to check available updates without installing
+- `--json` flag for machine-readable output
+- Updates install into the running Ruby's GEM_HOME (safe for Homebrew bundled installs)
+
+## [1.4.26] - 2026-03-16
+
+### Added
+- `Legion::Metrics` module: opt-in Prometheus metrics via `prometheus-client` gem
+- `GET /metrics` endpoint returning Prometheus text-format output
+- 9 metrics: uptime, active_workers, tasks_total, tasks_per_second, error_rate, consent_violations, llm_requests, llm_tokens
+- Event-driven counters + pull-based gauge refresh on scrape
+- `/metrics` added to Auth middleware SKIP_PATHS
+- Wired into Service startup and shutdown
+
+## [1.4.25] - 2026-03-16
+
+### Added
+- `Legion::Chat::NotificationQueue`: thread-safe priority queue for background notifications
+- `Legion::Chat::NotificationBridge`: event-driven bridge matching Legion events to chat notifications
+- Chat REPL displays pending notifications before each prompt (critical in red, info in yellow)
+- Configurable notification patterns via `chat.notifications.patterns` setting
+
+## [1.4.24] - 2026-03-16
+
+### Added
+- `Legion::Audit.recent_for` — query audit records by principal and time window
+- `Legion::Audit.count_for` — count audit records by principal and time window
+- `Legion::Audit.failure_count_for` / `success_count_for` — convenience wrappers
+- `Legion::Audit.resources_for` — distinct resources invoked by a principal
+- `Legion::Audit.recent` — most recent N records with optional filters
+- All query methods return safe defaults (`[]` or `0`) when legion-data is unavailable
+
+## [1.4.23] - 2026-03-16
+
+### Added
+- `Middleware::BodyLimit`: request body size limit (1MB max, returns 413)
+- `API::Validators` helper module: `validate_required!`, `validate_string_length!`, `validate_enum!`, `validate_uuid!`, `validate_integer!`
+- Ingress payload validation: 512KB size limit, runner_class/function format checks
+
+### Security
+- Ingress validates runner_class format before `Kernel.const_get` to prevent arbitrary constant resolution
+- Ingress validates function format before `.send` to prevent method injection
+
+## [1.4.22] - 2026-03-16
+
+### Added
+- `Legion::Alerts`: configurable alerting rules engine with event pattern matching
+- `Alerts::Engine`: count-based conditions, cooldown deduplication, multi-channel dispatch
+- 4 default rules: consent_violation, extinction_trigger, error_spike, budget_exceeded
+- Channel dispatch: events (via `Legion::Events`), log (via `Legion::Logging`), webhook
+- Settings: `alerts.enabled`, `alerts.rules`
+- Wired into `Service` startup (opt-in via `alerts.enabled: true`)
+
+## [1.4.21] - 2026-03-16
+
+### Added
+- `Middleware::ApiVersion`: rewrites `/api/v1/` paths to `/api/` for future versioned API support
+- Deprecation headers (`Deprecation`, `Sunset`, `Link`) on unversioned `/api/` paths
+- `X-API-Version` request header set for versioned paths
+- Skip paths: `/api/health`, `/api/ready`, `/api/openapi.json`, `/metrics`
+
+## [1.4.20] - 2026-03-16
+
+### Added
+- `Middleware::RateLimit`: sliding-window rate limiting with per-IP, per-agent, per-tenant tiers
+- In-memory store (default) with lazy reap; distributed store via `Legion::Cache` when available
+- Standard headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` (429 only)
+- Skip paths: `/api/health`, `/api/ready`, `/api/metrics`, `/api/openapi.json`
+
+## [1.4.19] - 2026-03-16
+
+### Added
+- Local development mode: `LEGION_LOCAL=true` env var or `local_mode: true` in settings
+- Auto-configures in-memory transport, mock Vault, and dev settings
+
+## [1.4.18] - 2026-03-16
+
+### Added
+- `legion config scaffold` auto-detects environment variables and enables providers
+- Detects: AWS_BEARER_TOKEN_BEDROCK, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, VAULT_TOKEN, RABBITMQ_USER/PASSWORD
+- Detects running Ollama on localhost:11434
+- First detected LLM provider becomes the default; credentials use `env://` references
+- JSON output includes `detected` array for automation
+
+## [1.4.17] - 2026-03-16
+
+### Added
+- `Legion::Audit` publisher module for immutable audit logging via AMQP
+- Audit hook in `Runner.run` records every runner execution (event_type, duration, status)
+- Audit hook in `DigitalWorker::Lifecycle.transition!` records state transitions
+- `GET /api/audit` endpoint with filters (event_type, principal_id, source, status, since, until)
+- `GET /api/audit/verify` endpoint for hash chain integrity verification
+- `legion audit list` and `legion audit verify` CLI commands
+- Silent degradation: audit never interferes with normal operation (triple guard + rescue)
+
+## [1.4.16] - 2026-03-16
+
+### Added
+- `legion worker create NAME` CLI command: provisions digital worker in bootstrap state with DB record + optional Vault secret storage
+
+## [1.4.15] - 2026-03-16
+
+### Added
+- RAI invariant #2: Ingress.run calls Registry.validate_execution! when worker_id is present
+- Unregistered or inactive workers are blocked with structured error (no exception propagation)
+- Registration check fires before RBAC authorization (registration precedes permission)
+
+## [1.4.14] - 2026-03-16
+
+### Added
+- Optional RBAC integration via legion-rbac gem (`if defined?(Legion::Rbac)` guards)
+- `GET /api/workers/:id/health` endpoint returns worker health status with node metrics
+- `health_status` query filter on `GET /api/workers`
+- Thread-safe local worker tracking in `DigitalWorker::Registry` for heartbeat reporting
+- `Legion::DigitalWorker.active_local_ids` delegate method
+- `setup_rbac` lifecycle hook in Service (after setup_data)
+- `authorize_execution!` guard in Ingress for task execution
+- Rack middleware registration in API when legion-rbac loaded
+- REST API routes for RBAC management (roles, assignments, grants, cross-team grants, check)
+- `legion rbac` CLI subcommand (roles, show, assignments, assign, revoke, grants, grant, check)
+- MCP tools: legion.rbac_check, legion.rbac_assignments, legion.rbac_grants
+
 ## [1.4.13] - 2026-03-16
 
 ### Changed

data/CLAUDE.md

@@ -9,7 +9,7 @@ The primary gem for the LegionIO framework. An extensible async job engine for s
 
 **GitHub**: https://github.com/LegionIO/LegionIO
 **Gem**: `legionio`
-**Version**: 1.4.13
+**Version**: 1.4.29
 **License**: Apache-2.0
 **Docker**: `legionio/legion`
 **Ruby**: >= 3.4
@@ -274,6 +274,7 @@ legion
   worker
     list [-s status] [-t risk_tier]
     show <id>
+    create <name> --entra_app_id ID --owner_msid EMAIL --extension NAME [--team T] [--client_secret S]
     pause <id>
     activate <id>
     retire <id>
@@ -346,6 +347,22 @@ legion
     bash                             # output bash completion script
     zsh                              # output zsh completion script
     install                          # print installation instructions
+
+  openapi
+    generate [-o FILE]               # output OpenAPI 3.1.0 spec JSON
+    routes                           # list all API routes with HTTP method + summary
+
+  doctor [--fix] [--json]            # diagnose environment, suggest/apply fixes
+                                     # checks: Ruby, bundle, config, RabbitMQ, DB, cache, Vault,
+                                     #   extensions, PID files, permissions
+                                     # exit 0=all pass, 1=any fail
+
+  telemetry
+    stats [SESSION_ID]               # aggregate or per-session telemetry stats
+    ingest PATH                      # manually ingest a session log file
+
+  auth
+    teams [--tenant-id ID] [--client-id ID]  # browser OAuth flow for Microsoft Teams
 ```
 
 **CLI design rules:**
@@ -450,7 +467,19 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/api/coldstart.rb` | Coldstart: `POST /api/coldstart/ingest` — triggers lex-coldstart ingest runner (requires lex-coldstart + lex-memory) |
 | `lib/legion/api/gaia.rb` | Gaia: system status endpoints |
 | `lib/legion/api/token.rb` | Token: JWT token issuance endpoint |
+| `lib/legion/api/openapi.rb` | OpenAPI: `Legion::API::OpenAPI.spec` / `.to_json`; also served at `GET /api/openapi.json` |
+| `lib/legion/api/oauth.rb` | OAuth: `GET /api/oauth/microsoft_teams/callback` — receives delegated OAuth redirect and stores tokens |
+| `lib/legion/audit.rb` | Audit logging: AMQP publish + query layer (recent_for, count_for, resources_for, recent) backed by AuditLog model |
+| `lib/legion/alerts.rb` | Configurable alerting rules engine: pattern matching, count conditions, cooldown dedup |
+| `lib/legion/telemetry.rb` | Opt-in OpenTelemetry tracing: `with_span` wrapper, `sanitize_attributes`, `record_exception` |
+| `lib/legion/metrics.rb` | Opt-in Prometheus metrics: event-driven counters, pull-based gauges, `prometheus-client` guarded |
+| `lib/legion/api/metrics.rb` | `GET /metrics` Prometheus text-format endpoint with gauge refresh |
+| `lib/legion/chat/notification_queue.rb` | Thread-safe priority queue for background notifications (critical/info/debug) |
+| `lib/legion/chat/notification_bridge.rb` | Event-driven bridge: matches Legion events to chat notifications via fnmatch patterns |
 | `lib/legion/api/middleware/auth.rb` | Auth: JWT Bearer auth middleware (real token validation, skip paths for health/ready) |
+| `lib/legion/api/middleware/api_version.rb` | ApiVersion: rewrites `/api/v1/` to `/api/`, adds Deprecation/Sunset headers on unversioned paths |
+| `lib/legion/api/middleware/body_limit.rb` | BodyLimit: request body size limit (1MB max, returns 413) |
+| `lib/legion/api/middleware/rate_limit.rb` | RateLimit: sliding-window rate limiting with per-IP/agent/tenant tiers |
 | **MCP** | |
 | `lib/legion/mcp.rb` | Entry point: `Legion::MCP.server` singleton factory |
 | `lib/legion/mcp/server.rb` | MCP::Server builder, TOOL_CLASSES array, instructions |
@@ -477,7 +506,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/cli/config_scaffold.rb` | `legion config scaffold` — generates starter JSON config files per subsystem |
 | `lib/legion/cli/generate_command.rb` | `legion generate` subcommands (runner, actor, exchange, queue, message) |
 | `lib/legion/cli/mcp_command.rb` | `legion mcp` subcommand (stdio + HTTP transports) |
-| `lib/legion/cli/worker_command.rb` | `legion worker` subcommands (list, show, pause, retire, terminate, activate, costs) |
+| `lib/legion/cli/worker_command.rb` | `legion worker` subcommands (list, show, create, pause, retire, terminate, activate, costs) |
 | `lib/legion/cli/coldstart_command.rb` | `legion coldstart` subcommands (ingest, preview, status) |
 | `lib/legion/cli/chat_command.rb` | `legion chat` — interactive AI REPL + headless prompt mode |
 | `lib/legion/cli/chat/session.rb` | Chat session: multi-turn conversation, streaming, tool use |
@@ -506,6 +535,10 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/cli/gaia_command.rb` | `legion gaia` subcommands (status) |
 | `lib/legion/cli/schedule_command.rb` | `legion schedule` subcommands (list, show, add, remove, logs) |
 | `lib/legion/cli/completion_command.rb` | `legion completion` subcommands (bash, zsh, install) |
+| `lib/legion/cli/openapi_command.rb` | `legion openapi` subcommands (generate, routes); also `GET /api/openapi.json` endpoint |
+| `lib/legion/cli/doctor_command.rb` | `legion doctor` — 10-check environment diagnosis; `Doctor::Result` value object with status/message/prescription/auto_fixable |
+| `lib/legion/cli/telemetry_command.rb` | `legion telemetry` subcommands (stats, ingest) — session log analytics |
+| `lib/legion/cli/auth_command.rb` | `legion auth` subcommands (teams) — delegated OAuth browser flow for external services |
 | `completions/legion.bash` | Bash tab completion script |
 | `completions/_legion` | Zsh tab completion script |
 | `lib/legion/cli/theme.rb` | Purple palette, orbital ASCII banner, branded CLI output |
@@ -544,7 +577,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 
 ```bash
 bundle install
-bundle exec rspec       # 880 examples, 0 failures
+bundle exec rspec       # 997 examples, 0 failures
 bundle exec rubocop     # 0 offenses
 ```
 

data/Gemfile

@@ -14,6 +14,7 @@ unless ENV['CI']
   gem 'legion-json',      path: '../legion-json'
   gem 'legion-llm',       path: '../legion-llm'
   gem 'legion-logging',   path: '../legion-logging'
+  gem 'legion-rbac',      path: '../legion-rbac'
   gem 'legion-settings',  path: '../legion-settings'
   gem 'legion-transport', path: '../legion-transport'
 

data/README.md

@@ -14,7 +14,7 @@ Schedule tasks, chain services into dependency graphs, run them concurrently via
          ╰──────────────────────────────────────╯
 ```
 
-**Ruby >= 3.4** | **v1.4.6** | **Apache-2.0** | [@Esity](https://github.com/Esity)
+**Ruby >= 3.4** | **v1.4.13** | **Apache-2.0** | [@Esity](https://github.com/Esity)
 
 ---
 
@@ -176,6 +176,7 @@ AI-as-labor with governance, risk tiers, and cost tracking:
 ```bash
 legion worker list                  # list workers
 legion worker show <id>             # worker detail
+legion worker create <name>         # register new worker (bootstrap state)
 legion worker pause <id>            # pause / activate / retire
 legion worker costs --days 30       # cost report
 ```
@@ -205,11 +206,32 @@ legion schedule list
 ```bash
 legion config show              # resolved config (redacted)
 legion config validate          # verify settings + subsystem health
-legion config scaffold          # generate starter config files
+legion config scaffold          # generate starter config files (auto-detects env vars)
 ```
 
+`config scaffold` auto-detects environment variables (`ANTHROPIC_API_KEY`, `AWS_BEARER_TOKEN_BEDROCK`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `VAULT_TOKEN`, `RABBITMQ_USER`/`PASSWORD`) and a running Ollama instance, enabling providers and setting `env://` references automatically.
+
 Settings load from the first directory found: `/etc/legionio/` → `~/legionio/` → `./settings/`
 
+### Diagnostics
+
+```bash
+legion doctor                   # diagnose environment, suggest fixes
+legion doctor --fix             # auto-remediate fixable issues (stale PIDs, missing gems)
+legion doctor --json            # machine-readable output
+```
+
+Checks Ruby version, bundle status, config files, RabbitMQ, database, cache, Vault, extensions, PID files, and permissions. Exits 1 if any check fails.
+
+### Updating
+
+```bash
+legion update                   # update all legion gems in-place
+legion update --dry-run         # check what's available without installing
+```
+
+Uses the same Ruby that `legion` is running from — safe for Homebrew installs (updates go into the bundled gem directory, not your system Ruby).
+
 All commands support `--json` for structured output and `--no-color` to strip ANSI codes.
 
 ## REST API
@@ -332,6 +354,25 @@ legion generate actor myactor
 bundle exec rspec
 ```
 
+## Role Profiles
+
+Control which extensions load at startup via `settings/legion.json`:
+
+```json
+{"role": {"profile": "dev"}}
+```
+
+| Profile | What loads |
+|---------|-----------|
+| *(default)* | Everything — no filtering |
+| `core` | 14 core operational extensions only |
+| `cognitive` | core + all agentic extensions |
+| `service` | core + service + other integrations |
+| `dev` | core + AI + essential agentic (~20 extensions) |
+| `custom` | only what's listed in `role.extensions` |
+
+Faster boot and lower memory footprint for dedicated worker roles.
+
 ## Scaling
 
 Task distribution uses RabbitMQ FIFO queues. Add workers by running more Legion processes — each subscribes to the same queues and picks up work automatically. Tested to 100+ workers.
@@ -363,6 +404,12 @@ CMD ruby --yjit $(which legion) start
 
 ## Architecture
 
+Before any Legion code loads, the executable applies three performance optimizations:
+
+- **YJIT** — `RubyVM::YJIT.enable` for 15-30% runtime throughput (Ruby 3.1+ builds)
+- **GC tuning** — pre-allocates 600k heap slots and raises malloc limits (ENV overrides respected)
+- **bootsnap** — caches YARV bytecodes and `$LOAD_PATH` resolution at `~/.legionio/cache/bootsnap/`
+
 ```
 legion start
   └── Legion::Service
@@ -374,13 +421,15 @@ legion start
       ├── 6. Data             (legion-data — database + migrations)
       ├── 7. LLM              (legion-llm — AI provider setup + routing)
       ├── 8. Supervision      (process supervision)
-      ├── 9. Extensions       (discover + load 280+ LEX gems)
+      ├── 9. Extensions       (discover + load 280+ LEX gems, filtered by role profile)
       ├── 10. Cluster Secret  (distribute via Vault or memory)
       └── 11. API             (Sinatra/Puma on port 4567)
 ```
 
 Each phase registers with `Legion::Readiness`. All phases are individually toggleable.
 
+`SIGHUP` triggers a live reload (`Legion.reload`) — subsystems shut down in reverse order and restart fresh without killing the process. Useful for rolling restarts and config changes.
+
 ## Similar Projects
 
 | Project | Language | HA | AI | Cognitive |
@@ -397,7 +446,7 @@ Each phase registers with `Legion::Readiness`. All phases are individually toggl
 git clone https://github.com/LegionIO/LegionIO.git
 cd LegionIO
 bundle install
-bundle exec rspec       # 694 examples, 0 failures
+bundle exec rspec       # 880 examples, 0 failures
 bundle exec rubocop     # 0 offenses
 ```
 

data/lib/legion/alerts.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Alerts
+    AlertRule = Struct.new(:name, :event_pattern, :condition, :severity, :channels, :cooldown_seconds)
+
+    DEFAULT_RULES = [
+      { name: 'consent_violation', event_pattern: 'governance.consent_violation', severity: 'critical',
+        channels: %w[events log], cooldown_seconds: 300 },
+      { name: 'extinction_trigger', event_pattern: 'extinction.*', severity: 'critical',
+        channels: %w[events log], cooldown_seconds: 0 },
+      { name: 'error_spike', event_pattern: 'runner.failure',
+        condition: { count_threshold: 10, window_seconds: 60 }, severity: 'warning',
+        channels: %w[events log], cooldown_seconds: 300 },
+      { name: 'budget_exceeded', event_pattern: 'finops.budget_exceeded', severity: 'warning',
+        channels: %w[events log], cooldown_seconds: 3600 }
+    ].freeze
+
+    class Engine
+      attr_reader :rules
+
+      def initialize(rules: [])
+        @rules = rules.map { |r| r.is_a?(AlertRule) ? r : AlertRule.new(**r.transform_keys(&:to_sym)) }
+        @counters = {}
+        @last_fired = {}
+      end
+
+      def evaluate(event_name, payload = {})
+        fired = []
+        @rules.each do |rule|
+          next unless event_matches?(event_name, rule.event_pattern)
+          next unless condition_met?(rule, event_name)
+          next if in_cooldown?(rule)
+
+          fire_alert(rule, event_name, payload)
+          fired << rule.name
+        end
+        fired
+      end
+
+      private
+
+      def event_matches?(name, pattern)
+        File.fnmatch?(pattern, name)
+      end
+
+      def condition_met?(rule, event_name)
+        cond = rule.condition
+        return true unless cond.is_a?(Hash)
+
+        key = "#{rule.name}:#{event_name}"
+        @counters[key] ||= { count: 0, window_start: Time.now }
+
+        window = cond[:window_seconds] || 60
+        @counters[key] = { count: 0, window_start: Time.now } if Time.now - @counters[key][:window_start] > window
+
+        @counters[key][:count] += 1
+        @counters[key][:count] >= (cond[:count_threshold] || 1)
+      end
+
+      def in_cooldown?(rule)
+        last = @last_fired[rule.name]
+        return false unless last
+
+        Time.now - last < (rule.cooldown_seconds || 0)
+      end
+
+      def fire_alert(rule, event_name, payload)
+        @last_fired[rule.name] = Time.now
+        alert = { rule: rule.name, event: event_name, severity: rule.severity,
+                  payload: payload, fired_at: Time.now.utc }
+
+        (rule.channels || []).each do |channel|
+          case channel.to_sym
+          when :events
+            Legion::Events.emit('alert.fired', alert) if defined?(Legion::Events)
+          when :log
+            Legion::Logging.warn "[alert] #{rule.name}: #{event_name} (#{rule.severity})" if defined?(Legion::Logging)
+          when :webhook
+            Legion::Webhooks.dispatch('alert.fired', alert) if defined?(Legion::Webhooks)
+          end
+        end
+      end
+    end
+
+    class << self
+      def setup
+        rules = load_rules
+        @engine = Engine.new(rules: rules)
+        register_listener
+        Legion::Logging.debug "Alerts: #{rules.size} rules loaded" if defined?(Legion::Logging)
+      end
+
+      attr_reader :engine
+
+      def reset!
+        @engine = nil
+      end
+
+      private
+
+      def load_rules
+        custom = begin
+          Legion::Settings[:alerts][:rules]
+        rescue StandardError
+          nil
+        end
+        custom && !custom.empty? ? custom : DEFAULT_RULES
+      end
+
+      def register_listener
+        return unless defined?(Legion::Events)
+
+        Legion::Events.on('*') do |event_name, **payload|
+          @engine&.evaluate(event_name, payload)
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/audit.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module Audit
+        def self.registered(app)
+          app.get '/api/audit' do
+            require_data!
+            dataset = Legion::Data::Model::AuditLog.order(Sequel.desc(:id))
+            dataset = dataset.where(event_type: params[:event_type])     if params[:event_type]
+            dataset = dataset.where(principal_id: params[:principal_id]) if params[:principal_id]
+            dataset = dataset.where(source: params[:source])             if params[:source]
+            dataset = dataset.where(status: params[:status])             if params[:status]
+            dataset = dataset.where { created_at >= Time.parse(params[:since]) } if params[:since]
+            dataset = dataset.where { created_at <= Time.parse(params[:until]) } if params[:until]
+            json_collection(dataset)
+          end
+
+          app.get '/api/audit/verify' do
+            require_data!
+            halt 503, json_error('unavailable', 'lex-audit is not loaded', status_code: 503) unless defined?(Legion::Extensions::Audit::Runners::Audit)
+
+            runner = Object.new.extend(Legion::Extensions::Audit::Runners::Audit)
+            result = runner.verify
+            json_response(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/metrics.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module Metrics
+        def self.registered(app)
+          app.get '/metrics' do
+            unless defined?(Legion::Metrics) && Legion::Metrics.available?
+              content_type 'text/plain'
+              halt 404, 'prometheus-client gem not available'
+            end
+
+            Legion::Metrics.refresh_gauges
+            content_type 'text/plain; version=0.0.4; charset=utf-8'
+            Legion::Metrics.render
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/middleware/api_version.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+
+module Legion
+  class API < Sinatra::Base
+    module Middleware
+      class ApiVersion
+        SKIP_PATHS = %w[/api/health /api/ready /api/openapi.json /metrics].freeze
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          path = env['PATH_INFO']
+
+          if path.start_with?('/api/v1/')
+            env['PATH_INFO'] = path.sub('/api/v1/', '/api/')
+            env['HTTP_X_API_VERSION'] = '1'
+            @app.call(env)
+          elsif path.start_with?('/api/') && !skip_path?(path)
+            status, headers, body = @app.call(env)
+            headers['Deprecation'] = 'true'
+            headers['Sunset'] = (Time.now + (180 * 86_400)).httpdate
+            successor = path.sub('/api/', '/api/v1/')
+            headers['Link'] = "<#{successor}>; rel=\"successor-version\""
+            [status, headers, body]
+          else
+            @app.call(env)
+          end
+        end
+
+        private
+
+        def skip_path?(path)
+          SKIP_PATHS.any? { |skip| path.start_with?(skip) }
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/middleware/auth.rb

@@ -4,7 +4,7 @@ module Legion
   class API < Sinatra::Base
     module Middleware
       class Auth
-        SKIP_PATHS      = %w[/api/health /api/ready /api/openapi.json].freeze
+        SKIP_PATHS      = %w[/api/health /api/ready /api/openapi.json /metrics].freeze
         AUTH_HEADER     = 'HTTP_AUTHORIZATION'
         BEARER_PATTERN  = /\ABearer\s+(.+)\z/i
         API_KEY_HEADER  = 'HTTP_X_API_KEY'

data/lib/legion/api/middleware/body_limit.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+
+module Legion
+  class API < Sinatra::Base
+    module Middleware
+      class BodyLimit
+        MAX_BODY_SIZE = 1_048_576 # 1MB
+
+        def initialize(app, max_size: MAX_BODY_SIZE)
+          @app = app
+          @max_size = max_size
+        end
+
+        def call(env)
+          content_length = env['CONTENT_LENGTH'].to_i
+          if content_length > @max_size
+            body = Legion::JSON.dump({
+                                       error: { code:    'payload_too_large',
+                                                message: "request body exceeds #{@max_size} bytes" },
+                                       meta:  { timestamp: Time.now.utc.iso8601 }
+                                     })
+            return [413, { 'content-type' => 'application/json' }, [body]]
+          end
+          @app.call(env)
+        end
+      end
+    end
+  end
+end