Orchestrator Architecture
The umbrella architecture record for Lex. Covers the conductor pattern, confidence hardening layer, and how routing, verification, policy, model capability, and telemetry contracts fit together.
Context
As adoption increased, confidence requirements became stricter than basic orchestration. Routing needed deterministic behavior, step completion needed hard evidence checks, failure handling needed explicit retry semantics, model behavior needed consistency, and telemetry needed stable attributes.
Core Decisions
1. Conductor Pattern Remains Non-Negotiable
Lex routes, sequences, enforces, and reports. Subagents execute domain work. Lex does not self-implement workflow tasks.
2. Capability Profile Abstraction
Model behavior is controlled by profile mapping rather than model-specific workflow forks. Supported profiles:
gpt-5.3gpt-5.2claude-opusclaude-sonnetbaselinefallback
Profiles control effort hints, compaction behavior, and context/output budgeting. Workflow YAML stays model-agnostic.
3. Verification-First Step Acceptance
Lex accepts a step only if verification evidence is present and valid. If evidence is missing, the step output is rejected and the configured onMissingEvidence policy is applied.
4. Policy-as-Code for Workflow Governance
A dedicated policy file governs retry ceilings, retry metadata requirements, mutating vs non-mutating workflow classification, review/verification requirements, and context cascade thresholds.
5. Routing Reliability Controls
Routing confidence is protected by a golden routing corpus, overlap/tie detection tests, and an explicit allowlist for known acceptable ambiguities.
6. Telemetry Contract Normalization
Standardized canonical agent names, checkpoint normalization (CP-1 through CP-6), legacy alias mapping, and sanitized bounded metric attributes.
7. Contract Regression Test Expansion
Confidence-critical tests now cover:
- Workflow graph safety (roots, cycles, terminal reachability)
- Policy compliance
- Template reference correctness
- Routing regressions and overlap risk
- Model profile coverage
- Telemetry contract consistency
Architecture Flow
User Request
A prompt or trigger enters the Lex orchestrator.
Routing & Workflow Selection
Lex scores the prompt against workflow triggers and selects the best match using the deterministic routing engine.
Agent Dispatch
Lex dispatches steps to maintainer or executor subagents via runSubagent, passing context and instructions.
Verification & Acceptance
Each step result is verified against evidence contracts before acceptance. Missing evidence triggers retry or abort.
Telemetry Emission
Normalized telemetry is emitted at each checkpoint for stable dashboards and alerting.