ue-toolchain/docs/architecture/decisions/0005-native-transport-narrows-adr-0001.md

status, date, deciders, consulted, informed, amends

status	date	deciders	consulted	informed	amends
accepted	2026-09-06	project owner	ADR-0001; live measurement of the engine's own MCP server (UE 5.8)	future contributors	0001-discovery-over-pid-file

The engine ships the transport; ADR-0001 narrows to what it still decides

Context and Problem Statement

ADR-0001 was written against one existing bridge, which tied a server to a PID file on disk. It rejected that and specified a replacement: our own JSON-RPC server inside the editor, our own UDP-broadcast discovery on a loopback port, our own heartbeat.

None of that was built. In the meantime the engine acquired an agent-tool layer of its own: an MCP server, a toolset registry, and skill assets discovered from the project. This was measured, not read about -- a live editor served a session over the documented endpoint, negotiated a protocol version, and answered a tool listing.

So the question ADR-0001 answered is no longer open in the same form. Building a second transport beside a first-party one is not a contest this project can win: it doubles the surface, and the vendor's version moves with the engine.

What ADR-0001 got right is separate from what it specified. Its reasoning was about liveness -- a file cannot say whether a process is alive, tools that require an editor must disappear when the editor does, and the client must recover without a restart. That reasoning survives a change of transport intact.

Decision Drivers

• Do not compete with the first party on transport. The server, the session model and the protocol ship and are maintained with the engine.
• A tool layer is still missing where it matters. The registry that serves toolsets is editor-only by declaration; the transport module is not. The one thing measurement shows nobody covers is tools that run in a live game outside the editor.
• The liveness contract from ADR-0001 is still the product. Its value was never the broadcast; it was that file-based tools keep working and editor-based ones vanish honestly.
• What we do not build, we do not have to keep working.

Decision Outcome

ADR-0001 is narrowed, not withdrawn. Its analysis stands; three of its mechanisms are dropped, and one is replaced.

Kept.

• The process is the source of truth, never a file on disk.
• File and analysis tools work with no editor present.
• Editor-dependent tools appear in the tool list only while a connection is live, and disappear on their own when it is not.
• Recovery without restarting the client.

Dropped.

• Our own JSON-RPC server inside the editor. The engine has one.
• UDP-broadcast discovery on a loopback port. Superseded below.
• Our own heartbeat protocol. The session layer already has one.

Replaced. Discovery becomes a probe of the engine's documented endpoint rather than a broadcast we invent: a configured host, port and URL path, with the endpoint's own answer deciding liveness. Measured behaviour that makes this cheap: a request to the wrong path returns a plain HTTP 404 with a routing error body, immediately and without hanging, and path matching tolerates case and a trailing slash. A wrong guess is therefore a fast negative, which is what a probe needs and what the PID file could not give.

What remains ours to build, and only this:

1. A server that runs without the engine, carrying file and analysis tools -- unchanged from ADR-0001, and the reason a component still exists at all.
2. Tools that run in a live game outside the editor, registered through the engine's public runtime interface. This is the one layer measurement shows is uncovered: the toolset registry and every toolset built on it are declared editor-only, while the transport module is not.

Explicitly not ours: the protocol, the server, the session model, the editor-side toolsets, and the skill-asset registry.

Consequences

• Good: phases 1 and 2 of the handoff shrink by an order of magnitude. There is no bridge plugin to write, no protocol to version, no discovery to debug.
• Good: the uncovered layer we take on -- runtime, outside the editor -- is the same territory as the one skill with no first-party equivalent. Scope and product need coincide rather than compete.
• Good: nothing in ADR-0001's liveness criteria is lost; they are restated below against the new transport.
• Bad: the project now depends on a plugin its author marks Experimental, with a stated warning that APIs and formats may change at any time. Accepted, and mitigated where it touches the delivery: ADR-0004 keeps that surface out of skill content entirely.
• Bad: two editors on one machine both default to the same port, and how the second behaves has not been measured. Under ADR-0001 this was our problem to solve; now it is a question to answer, and it is listed as open rather than assumed benign.
• Neutral: the rejected design is not deleted. ADR-0001 keeps its four arguments against the PID file, which is why the replacement is a probe with a fast negative and not another file.

Confirmation

Required before this ADR is treated as implemented:

• Cold start with no editor running: file and analysis tools answer, editor tools are absent from the tool list, no call blocks.
• Editor running: editor tools become reachable after a probe, and the probe's negative path costs one fast HTTP response rather than a timeout. (the negative path is already measured: HTTP 404 with a routing error body, no hang)
• Editor closed mid-session: editor tools disappear without a client restart and no call hangs waiting for them.
• Editor restarted: tools return without restarting the client.
• A runtime tool registered through the engine's public interface answers in a packaged build with no editor present. Not yet attempted -- this is the load-bearing claim of the whole narrowing, and until it runs, item 2 above is derived, not measured.

Deferred

• Two editors, one default port. Which instance binds, what the second reports, and whether the client can address a specific project. Unmeasured; do not guess it.
• Whether an editor-side component is ever needed. Nothing requires one today. If one appears, it should arrive as its own ADR with a reason, not as scope creep into this one.
• Remote operation. Deferred by ADR-0001 and still deferred. Nothing measured here changes that.