browser/openspec/changes/fix-run-build-worker-role/design.md

Context

Platform dispatches distribution.build through a trusted Run endpoint. A newer server lifecycle already distinguishes DeploymentTargetID from a dedicated RunEndpointID, but legacy instances can still have only RunEndpointID. A generated Run for such an instance was built with the shared endpoint identity and its component key, so starting it remotely replaced the local build worker registration.

Goals / Non-Goals

Goals:

• Preserve a local trusted Run worker as the only component that compiles generated Windows Run binaries.
• Give generated Run packages a deterministic server-scoped identity.
• Make legacy generation self-heal the unsafe endpoint binding before a build is queued.
• Prevent generated Run packages from advertising build-only worker capabilities.

Non-Goals:

• Do not move compilation into the browser, expose source trees to plugins, or require Go/Git on the game host.
• Do not alter deployment commands, game dependencies, or remote server files.

Decisions

1. When a failed or draft legacy instance requests a Run distribution, Platform atomically promotes its existing endpoint to DeploymentTargetID and reserves server-run-<server-id> as the generated Run endpoint. Generation is an explicit operator action and is the safe migration boundary; it avoids changing active legacy instances merely because Platform starts.
2. Component-authenticated Run hello must match the instance's dedicated Run endpoint. A component token cannot register over a shared build endpoint.
3. Run capability reporting is role-aware. A component-authenticated generated Run keeps lifecycle/file/dependency capabilities but never reports distribution build or Run self-update capabilities. A generic worker remains build-capable.
4. Source-preparation failures return a bounded category that distinguishes unavailable source, invalid source layout, and unsafe source content without exposing host paths.

Risks / Trade-offs

• [A failed legacy instance needs a fresh package] → Generation performs the migration before queueing and produces a package with the new identity.
• [A stale remotely deployed package continues to reconnect] → Platform rejects it after migration because its endpoint ID no longer matches the component's dedicated identity.
• [Role-aware capabilities change scheduling] → Only build-only capabilities are removed from component packages; normal server lifecycle capability reporting is preserved.

Migration Plan

1. Deploy Platform and Run changes.
2. Start the local generic build worker with run-local-debug and its approved source snapshot.
3. Generate Run for the failed legacy server; Platform promotes run-local-debug to its deployment target and embeds server-run-<id> in the new Windows package.
4. Replace the old remote executable with the generated package; its stale shared-ID registration is rejected.
5. Roll back by retaining the old package and restoring the legacy binding only through an explicit recovery operation; Platform never silently maps a component token onto a shared builder endpoint.

Open Questions

• None.