browser/openspec/changes/separate-server-run-binding/design.md

Context

ServerInstance.RunEndpointID currently points at a global endpoint selected while creating the server. That endpoint both executes the initial install/build jobs and is later treated as the endpoint for a generated, server-scoped Run. The type has no server ownership, registration accepts any endpoint ID after validating only the component key, and reset revokes the shared endpoint session. The browser consequently asks for a Run before the server-specific Run exists.

Goals / Non-Goals

Goals:

• Keep a server bound to exactly one dedicated Run endpoint after registration.
• Preserve an explicit deployment target for target OS, architecture, and trusted build work without treating it as the server Run.
• Make draft creation, reserved endpoint identity, Run registration, deployment, replacement, and revocation stateful and auditable.
• Prevent authenticated Run binaries from claiming another server endpoint or jobs.

Non-Goals:

• Adding host provisioning, SSH, a second executor source tree, or browser access to host paths and credentials.
• Migrating already-active legacy server endpoints automatically; they remain readable and are handled through an explicit future migration.
• Changing plugin runtime-profile, channel isolation, or artifact confidentiality rules.

Decisions

1. Store deployment target and dedicated Run separately

ServerInstance gains DeploymentTargetID while RunEndpointID is reserved for the dedicated endpoint. A server draft can have a target but no Run endpoint. The target must be an online compatible endpoint with distribution.build; it is used only to build the dedicated Run package. Lifecycle deployment and subsequent runtime work require the dedicated endpoint.

This avoids overloading an existing field. Reusing RunEndpointID with a role enum would leave historical jobs and control sessions ambiguous.

2. Reserve deterministic endpoint ownership before package generation

The dedicated Run endpoint ID is deterministic (server-run-<server instance id>). Package generation persists that reserved identity. A component-authenticated hello must use this identity, name the same server and Run component, and is rejected if the endpoint belongs to another server. Control registration records the ownership only after all checks pass.

This avoids a browser-chosen endpoint ID and permits Run to self-register without exposing a registration credential separate from the component key.

3. Draft first; deployment is explicit

The create workflow always creates a draft; choosing a deployment target does not queue installation. After a Run package is generated, downloaded, and registers online, the operator explicitly deploys the definition. This removes the bootstrap loop and keeps all execution behind an authenticated Run.

4. Use a focused additive migration

The new fields are additive. Legacy instances with a populated RunEndpointID and no DeploymentTargetID keep their existing behavior through a compatibility branch. New server workflow requests use the new draft path. A later migration can opt legacy records into exclusive ownership only after operational review.

Risks / Trade-offs

• [A build target must already exist] → The UI calls it a deployment target and explains that it is a trusted build worker, not the dedicated Run.
• [Legacy endpoints can be shared] → New exclusive ownership checks apply only to newly reserved endpoints; legacy records are not silently broken.
• [Registration failure leaves a package unusable] → The server remains a recoverable draft with a redacted reason and can regenerate/reset the Run key.
• [Run repository must adopt the identity] → Document the revised hello contract and gate deployment until matching registration occurs.

Migration Plan

1. Add additive domain/model/DTO fields and persistence compatibility.
2. Create new servers as target-bound drafts and generate packages through their deployment target.
3. Require reserved identity checks at component hello and only dispatch deployment to the dedicated endpoint.
4. Update the independent Run implementation to send the reserved endpoint ID, then enable the new workflow in environments that have it.
5. Roll back by leaving new servers as drafts; no browser or platform fallback executes work directly on a target host.

Open Questions

• The independent Run repository must consume the returned/reserved endpoint identity before an end-to-end real-machine rollout.