Gateway Architecture

v4.2.0 Gateway Foundation includes contracts, runtime-readable registries, deterministic dry-run routing, resilience simulation, a localhost mock gateway runtime, preview-only client configuration, and bounded local observability.

v4.2.0 is prepared for release but not npm-published yet. v4.1.0 remains npm latest until manual publication is complete.

The current runtime can start a local HTTP server for the mock provider only. MultiModel Dev OS still does not call external providers, load provider credentials, execute live retry/fallback chains, or enforce Skill OS permissions at runtime.

The gateway foundation is split into four planes:

Control Plane

Skill OS remains the governance layer:

• RACE+ prompt templates
• skill registry metadata
• workflow metadata
• declarative permission classes
• advisory guardrails
• memory and context files
• validation checks

The control plane is declarative. It describes policy and intent, but it does not execute provider calls or enforce runtime permissions yet.

Routing Plane

The routing plane is planned to choose a provider and model for a request. Sprint A only defines routing request and route decision contracts.

Planned routing inputs include:

• requested provider or model
• required and preferred capabilities
• estimated input tokens
• required context window
• privacy policy
• cost and latency preference
• excluded providers or models
• fallback allowance

Route decisions are designed to be explainable through selected provider/model, strategy, score, reasons, rejected candidates, fallback chain, warnings, request ID, and timestamp.

Gateway Plane

The future gateway plane is expected to expose a local OpenAI-compatible subset. Sprint A only defines protocol shapes and validation helpers.

Planned gateway responsibilities:

• request normalization
• response normalization
• normalized error taxonomy
• provider adapter invocation
• streaming abstraction
• usage metadata
• security boundaries
• health metadata

The gateway server exists for the local mock provider only. External provider execution remains excluded.

Client Plane

Client profiles and preview-only configuration plans exist for common coding agents and generic clients. They do not install or execute third-party clients, write global configuration, or validate external provider execution.

Source Layout

Sprint A adds pure contract modules under:

src/gateway/
  protocol/
  contracts/

The modules are deterministic and dependency-free. They do not read credentials, mutate the environment, write files, open sockets, or make network calls.

Runtime Registry Layer

v4.2 Sprint B adds a runtime-readable registry layer for existing .ai/models/ metadata. It loads and validates providers, hosted models, local model metadata, and routing presets into deterministic snapshots.

This layer still does not execute providers, read credential values, start local engines, score routes, or run fallback chains. It only prepares safe metadata for future routing code.

Deterministic Routing Layer

v4.2 Sprint C adds pure route planning on top of the runtime registry snapshot. It can rank viable candidates, return rejected-candidate reasons, produce fallback plans, and explain the decision.

Sprint C still does not contact providers, execute model requests, execute fallback attempts, start a gateway server, read provider credential values, or enforce Skill OS permissions at runtime.

Sprint D Resilience Simulation

v4.2 Sprint D adds deterministic resilience planning contracts on top of Sprint C route decisions:

• failure classification
• retry eligibility
• retry-budget planning
• deterministic backoff schedules
• timeout budget planning
• fallback transition planning
• circuit-breaker state simulation
• rate-limit and quota response planning
• resilience events
• full failure-chain simulation

Sprint D remains simulation-only. It does not contact providers, perform retries, perform provider failover, wait on timeout budgets, persist circuit-breaker state, or read credentials.

Sprint E Local Mock Runtime

v4.2 Sprint E introduces the first local HTTP runtime. It binds to localhost by default and serves a minimal OpenAI-compatible subset through a deterministic mock provider.

Sprint E supports:

• GET /health
• GET /v1/models
• POST /v1/chat/completions
• non-streaming mock chat
• deterministic mock SSE streaming
• request limits and timeouts
• bearer-token authentication for explicit non-local configurations
• clean server start/stop lifecycle

External providers remain metadata-only. Sprint E does not execute real provider requests, execute retry/fallback chains, load provider credentials, or persist request logs.

Sprint F Client Integration Planning

v4.2 Sprint F adds a client integration layer around the local runtime:

• client capability profiles
• endpoint configuration normalization
• preview-only configuration plans
• redacted diagnostics
• local mock compatibility tests

It does not install or execute third-party clients, write user-global configuration, enable external providers, or turn the gateway into a production multi-provider service.

Sprint G Local Observability

v4.2 Sprint G adds a local observability plane for the mock runtime:

• redacted request lifecycle events
• request traces
• usage records
• static cost estimates
• metrics snapshots
• mock-provider health snapshots

This plane is local-only and bounded. It does not upload telemetry, persist logs, retain prompt/completion content by default, or probe external providers.

Safety Boundary

Gateway architecture work must preserve:

• zero runtime dependencies
• localhost-first defaults
• prompt redaction by default
• no committed provider credentials
• no hidden provider execution
• no runtime permission enforcement until explicitly implemented and documented

See Gateway API Reference, Gateway OpenAI Compatibility, and v4.2 Known Limitations for the current hardening snapshot.