Epic: Legacy gateway transition, feature freeze, deprecation, and extraction

Decision

The MCP gateway remains supported during the transition, but it is no longer the product's strategic center. ContextWeaver's target architecture is an offline capability compiler plus a phase-aware runtime; the host owns execution.

This epic governs a strangler migration from the current gateway/runtime surface to compiler-first APIs without breaking existing users prematurely.

Phase 0 — freeze the execution platform

Allowed gateway work:

• security and correctness fixes;
• compatibility and data-loss fixes;
• dependency maintenance;
• documenting limitations;
• simplification and migration tooling;
• telemetry required to understand migration risk.

Not accepted as new core scope:

• new execution modes;
• new authentication/authorization systems;
• richer retry or orchestration semantics;
• distributed state or control-plane capabilities;
• code execution;
• runtime caching platforms;
• gateway-specific observability expansion unrelated to compiler migration.

Phase 1 — deliver the replacement

The transition cannot advance until these exist:

• compiler input/configuration model;
• multi-source discovery and normalized snapshots;
• versioned compiled artifact;
• CompiledAgent.load(...);
• route(...), hydrate(...), build_context(...), and ingest_result(...);
• host executor and normalized-result seam;
• representative evaluation and the compiler killer demo.

Phase 2 — migrate users and documentation

• make compiler-first examples the default;
• provide side-by-side migration recipes;
• inventory current gateway public APIs and usage;
• identify reusable discovery/hydration behavior;
• prototype an optional MCP adapter that exposes compiled discovery/hydration without making execution a core responsibility.

Phase 3 — deprecate legacy execution

Candidate legacy surfaces include tool_execute, proxy execution, gateway-owned auth/retry/cache/state behavior, and execution-specific result handling.

Deprecation requirements:

• replacement documented and demonstrated;
• migration guide available;
• deprecation warning active for at least one release;
• release notes name the alternative;
• host-executor seam demonstrated with at least two runtime styles;
• normalized result reintegration works;
• usage inventory completed.

Phase 4 — extract or remove

After migration evidence, decide separately for each remaining capability:

• retain as a compatibility adapter;
• move to a host/runtime example;
• extract to a more appropriate repository/package;
• remove after the documented support window.

Compatibility promise

• compiler-first candidates may become stable for 1.0;
• immature compiler/enrichment/custom-phase surfaces remain experimental;
• gateway execution is legacy transition support and is not guaranteed through 1.0;
• no execution API is removed before replacement coverage, migration documentation, and at least one deprecation release.

Observability scope

Rewrite prior gateway-observability goals around:

• source discovery and coverage;
• compilation provenance and drift;
• bundle composition and containment;
• routing/evaluation quality;
• legacy usage and migration readiness.

Do not build a new general MCP operations/control plane inside this epic.

Completion criteria

• gateway freeze is documented and enforceable in issue review;
• compiler-first replacement covers the supported migration path;
• docs/examples no longer present gateway execution as the primary identity;
• each legacy execution surface has a keep/extract/remove decision;
• the final deprecation/removal plan is evidence-based.

Start by inventorying the current gateway public APIs, including tool_execute and proxy execution, then compare them with the listed compiler-first seams such as CompiledAgent.load(...), route(...), hydrate(...), build_context(...), and ingest_result(...). Done means the migration path, documentation, deprecation requirements, and keep/extract/remove decisions are supported by evidence.