From 08e9679b069f99d5942fe5c8124d32093dd5c23f Mon Sep 17 00:00:00 2001 From: MagentaDolphin Date: Sun, 6 Sep 2026 01:43:18 +0700 Subject: [PATCH] docs(adr-0005): narrow ADR-0001 to what the native transport leaves open The engine now ships an MCP server, a toolset registry and skill assets -- measured against a live editor rather than read about. Building a second transport beside it is not a contest this project can win. ADR-0001 is narrowed, not withdrawn. Its liveness reasoning survives intact: process over file, tools that vanish honestly, recovery without a restart. Three mechanisms are dropped (own JSON-RPC server, UDP-broadcast discovery, own heartbeat) and discovery becomes a probe of the documented endpoint, which the measurement showed gives a fast negative -- HTTP 404 with a routing error body, no hang. That is the property the PID file could not provide. Two layers stay ours: a server that runs without the engine, and tools that run in a live game outside the editor, the layer the registry's editor-only declaration leaves uncovered. The load-bearing claim is flagged as not yet attempted: a runtime tool answering in a packaged build. Until that runs it is derived, not measured. Co-Authored-By: Claude Opus 5 --- README.md | 1 + .../0005-native-transport-narrows-adr-0001.md | 124 ++++++++++++++++++ docs/handoff.md | 4 +- 3 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 docs/architecture/decisions/0005-native-transport-narrows-adr-0001.md diff --git a/README.md b/README.md index 5ec4d47..4d6fb1c 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ - [ADR-0002: Harness-neutral skill bundle](docs/architecture/decisions/0002-harness-neutral-skill-bundle.md) — репозиторий как маркетплейс, `catalog.json` как источник истины, манифест вендора как адаптер. Нейтральность проверяется гейтом, а не обещается. - [ADR-0003: Split licensing](docs/architecture/decisions/0003-split-licensing-prose-and-code.md) — проза бандла под CC BY-ND 4.0, код и метаданные под Apache-2.0; правообладатель назван, атрибуция в титрах — просьба, а не условие. - [ADR-0004: Engine tool surface out of skill content](docs/architecture/decisions/0004-engine-tool-surface-out-of-skill-content.md) — имена тулсетов, мета-тулов и эндпоинтов движка не попадают в `skills/`: слой экспериментальный, а его отказ молчалив. Проверяется правилом гейта P17. +- [ADR-0005: Native transport narrows ADR-0001](docs/architecture/decisions/0005-native-transport-narrows-adr-0001.md) — движок привёз свой MCP-сервер; свой мост, UDP-discovery и heartbeat сняты, контракт живости сохранён. Нашими остаются два слоя: сервер без редактора и тулы в рантайме. ## Лицензия diff --git a/docs/architecture/decisions/0005-native-transport-narrows-adr-0001.md b/docs/architecture/decisions/0005-native-transport-narrows-adr-0001.md new file mode 100644 index 0000000..67d0552 --- /dev/null +++ b/docs/architecture/decisions/0005-native-transport-narrows-adr-0001.md @@ -0,0 +1,124 @@ +--- +status: accepted +date: 2026-09-06 +deciders: project owner +consulted: ADR-0001; live measurement of the engine's own MCP server (UE 5.8) +informed: future contributors +amends: 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. diff --git a/docs/handoff.md b/docs/handoff.md index f7e46fd..f135441 100644 --- a/docs/handoff.md +++ b/docs/handoff.md @@ -14,7 +14,9 @@ > | компонент `skills/` в корне | репозиторий — маркетплейс, бандл на уровень глубже ([ADR-0002](architecture/decisions/0002-harness-neutral-skill-bundle.md)) | > | «Лицензия TBD, планируется MIT» (вопрос 2) | решено: проза CC BY-ND 4.0, код Apache-2.0 ([ADR-0003](architecture/decisions/0003-split-licensing-prose-and-code.md)) | > | `docs/licensing-options.md` как открытый выбор | материал к решению, само решение — в ADR-0003 | -> | целевая версия UE открыта (вопрос 5) | бандл измерен на 5.6; платформа исследования переведена на 5.8 (`LyraResearch/plans/ue58-native-mcp-strategy.md`). В поставку решение ещё не доехало — **открыто** | +> | целевая версия UE открыта (вопрос 5) | платформа — 5.8; решено 2026-09-06 прогнать все 232 рецепта по 5.8-дереву и развести версии по результату | +> | фазы 1–2: свой мост и MCP-сервер | сужены [ADR-0005](architecture/decisions/0005-native-transport-narrows-adr-0001.md): транспорт берём у движка | +> | вопрос 1, публичность | приватный Gitea `git.kodlo.art`; remote ещё не заведён | > > Открытыми остаются вопросы 1, 3, 4 и 5 из §6.