browser/openspec/changes/implement-run-control-registration/specs/run-control-registration/spec.md

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