## ADDED Requirements

### Requirement: Run control payloads are typed and bounded
The system SHALL define typed run control payloads for hello registration, hello response, heartbeat, heartbeat response, capability report, and capacity report without carrying logs, artifact chunks, job result bodies, host paths, raw credentials, or direct sockets.

#### Scenario: Control payloads are used
- **WHEN** run or platform code sends control registration or heartbeat data
- **THEN** it MUST use named protocol/DTO types from dedicated protocol or DTO packages

#### Scenario: Control payload stays lightweight
- **WHEN** run sends hello or heartbeat
- **THEN** the request MUST include run ID, display name, version, status, capability summary, and capacity metadata only

### Requirement: Platform accepts run hello registration
The platform SHALL expose a hello endpoint that accepts a run registration request, validates it, persists or updates the run endpoint metadata, and returns a platform-generated session token with polling hints.

#### Scenario: New run endpoint registers
- **WHEN** run sends a valid hello request for an unknown run endpoint
- **THEN** platform MUST create a run endpoint, mark it online, store capabilities/capacity, and return an accepted hello response with a session token

#### Scenario: Existing run endpoint registers again
- **WHEN** run sends a valid hello request for an existing run endpoint
- **THEN** platform MUST update version, display name, capabilities, capacity, heartbeat time, and return a new accepted hello response

#### Scenario: Invalid hello request is submitted
- **WHEN** run sends a missing ID, missing registration token, invalid capacity, or empty required metadata
- **THEN** platform MUST return a JSON validation error and MUST NOT create a run endpoint

### Requirement: Platform accepts authenticated run heartbeat
The platform SHALL expose a heartbeat endpoint that requires the active platform-issued session token for the target run endpoint and updates status, capacity, heartbeat time, and capability fingerprint state.

#### Scenario: Heartbeat succeeds
- **WHEN** run sends a heartbeat with the active session token
- **THEN** platform MUST update the run endpoint heartbeat metadata and return an accepted heartbeat response with the next heartbeat interval

#### Scenario: Heartbeat uses invalid session token
- **WHEN** run sends a heartbeat with a missing or stale session token
- **THEN** platform MUST reject it with a JSON validation error and MUST NOT update the endpoint metadata

#### Scenario: Capability fingerprint changes
- **WHEN** run heartbeat reports a capability fingerprint that differs from platform's known fingerprint
- **THEN** platform MUST accept the heartbeat and request capability refresh in the heartbeat response

### Requirement: Run client performs control registration calls
The run-side platform client SHALL provide typed hello and heartbeat methods that call the platform control endpoints and decode typed responses.

#### Scenario: Run sends hello through client
- **WHEN** run code calls the hello client method
- **THEN** the client MUST send a JSON `POST` to `/api/v1/run/control/hello` and decode the hello response

#### Scenario: Run sends heartbeat through client
- **WHEN** run code calls the heartbeat client method
- **THEN** the client MUST send a JSON `POST` to `/api/v1/run/control/heartbeat` and decode the heartbeat response

#### Scenario: Platform returns error
- **WHEN** the platform control endpoint returns a non-success status
- **THEN** the run client MUST return an error and MUST NOT treat the control call as accepted

### Requirement: Control registration is documented separately from heavier channels
The run/platform route and protocol documentation SHALL identify implemented control registration routes and explicitly defer job, log, artifact, and game client bridge transport.

#### Scenario: Contributor inspects control docs
- **WHEN** a contributor opens run or platform protocol docs
- **THEN** the docs MUST show hello/heartbeat routes as implemented and heavier channels as deferred

### Requirement: Control registration is verified
The change SHALL include platform service/API tests, run client tests, and an integration-style hello/heartbeat flow test.

#### Scenario: Verification commands run
- **WHEN** the change is complete
- **THEN** `go test ./...` from `platform/`, `go test ./...` from `run/`, `scripts/check-structure.sh`, and `openspec validate implement-run-control-registration --strict` MUST pass