Add EdgeZero migration plan

[aram356]

Summary

• Adds docs/internal/EDGEZERO_MIGRATION.md — comprehensive migration plan for moving trusted-server from direct Fastly Compute SDK to the EdgeZero framework
• Covers crate restructuring (core + adapter-per-platform), platform trait design (7 traits + RuntimeServices), 17-PR phased execution across 5 phases, dependency graph, per-PR acceptance criteria, and issue backlog
• All EdgeZero upstream dependencies link to stackpop/edgezero issues via id: filter queries

Closes #502

Test plan

• Document renders correctly on GitHub (tables, mermaid graph, code blocks)
• All EdgeZero issue links resolve to the correct issues
• No CI impact (documentation only)

[ChristianPavilonis]

Approval

This is a production-grade migration plan. The codebase analysis is accurate against both trusted-server and EdgeZero as they stand today. The behavior-first strategy is the right call, the phasing is sound, the dependency graph is correct, and the risk callouts are appropriate. Approved.

---

Issues to Address

The following items should be resolved before execution begins. None are structural problems — they're design clarifications and risk mitigations.

1. PlatformClientInfo trait should extract-once, not extract-per-call

The plan defines PlatformClientInfo with client_ip(req), tls_protocol(req), tls_cipher(req) — but the req parameter type is ambiguous. In Phase 1 handlers still use fastly::Request, but you can't pass that to a platform-agnostic trait.

EdgeZero already solves this with its FastlyRequestContext pattern: extract client info once at dispatch time and store it. The trait should follow the same extract-once-at-entry pattern:

pub trait PlatformClientInfo: Send + Sync {
    fn client_ip(&self) -> Option<IpAddr>;
    fn tls_protocol(&self) -> Option<String>;
    fn tls_cipher(&self) -> Option<String>;
}

The adapter constructs a ClientInfo struct from the platform request at the entry point, stores it in RuntimeServices, and handlers read it from there. No request parameter needed.

Affects: PR 2 trait contract, PR 7 wiring.

2. PlatformHttpClient should replace EdgeZero's ProxyClient, not coexist with it

The plan defines PlatformHttpClient with send(), send_async(), and select(). EdgeZero already has ProxyClient with send(ProxyRequest) -> Result<ProxyResponse>. These serve overlapping purposes with different APIs, and the plan doesn't clarify the relationship.

Recommendation: ProxyClient in EdgeZero should be refactored into a more generic HttpClient trait that supports both synchronous proxy-style sends and the async fan-out pattern (send_async + select). The trusted-server's PlatformHttpClient requirements (async fan-out, backend correlation, WASM-compatible) are a superset of what ProxyClient offers — this is a good forcing function to generalize EdgeZero's outbound HTTP abstraction rather than building a parallel one. File an EdgeZero issue for this refactor and have PlatformHttpClient align with whatever the generalized trait looks like.

Affects: PR 2 trait design, PR 6 implementation, EdgeZero backlog.

3. PR 13 risk mitigation — consider a preparatory PR for RuntimeServices threading

PR 13 combines three concerns: (a) RuntimeServices threading through integration/provider entry points, (b) fastly::Request/Response → http type migration across all 8+2 impls, and (c) send()/send_async() migration to RuntimeServices::http_client. This could be 3000+ lines.

Suggestion: Insert a preparatory PR between 12 and 13 that adds &RuntimeServices to IntegrationProxy::handle and AuctionContext without changing any types. This is a pure signature-change PR (adding a parameter), independent of the type swap, and it compiles with Fastly types still in place. It halves PR 13's scope by splitting "RuntimeServices plumbing" from "type migration + send migration."

Affects: PR dependency graph (adds PR 12.5), PR 13 scope.

4. tokio dependency in common crate needs removal

crates/common/Cargo.toml line 43 has tokio = { workspace = true }, and CLAUDE.md says "no Tokio or OS-specific dependencies in core crates." After migration, trusted-server-core targeting wasm32-wasip1 and wasm32-unknown-unknown should not depend on tokio. Add this to PR 15's cleanup scope.

Affects: PR 15.

---

Minor Notes (no action required, just awareness)

• http crate version compatibility is a non-issue. Both fastly = "0.11.12" and EdgeZero use http 1.x. The plan flags this as a "Risk" in PR 1 — downgrade to "Verify: expected compatible."
• PlatformResponse wrapper .into_inner() call sites will break in PR 12 when the inner type switches from fastly::Response to http::Response. This is fine (compiler catches it), but worth noting in PR 12's scope description as expected churn.
• Week 3-4 parallelism is optimistic. PRs 3, 6, 7, 8, 10 all touch main.rs for wiring, and the entry-point merge rule serializes them. PRs 7/8/10 may slip to week 5. Acknowledge in timeline notes.
• std::time::Instant in auction/orchestrator.rs:7 works on wasm32-wasip1 via WASI but not on wasm32-unknown-unknown (Cloudflare). EdgeZero uses web-time for this. Note as a cleanup item for PR 17 scope.
• PR 8 (content rewriting) is confirmed trivial. html_processor.rs, streaming_processor.rs, and all nextjs/ submodules have zero fastly:: imports. This is a verification-and-document PR.