init

protocol/control.md

@@ -0,0 +1,28 @@
+# Run Control Contract
+
+Control is the lightweight high-priority channel between run and platform.
+
+## Implemented Routes
+
+- `POST /api/v1/run/control/hello`: registers run metadata and receives a platform-issued session token.
+- `POST /api/v1/run/control/heartbeat`: reports status, capacity, and capability fingerprint using the active session token.
+
+## Payloads
+
+- `RunHelloRequest`: registration token, run ID, display name, version, status, platform, capability summary, and capacity summary.
+- `RunHelloResponse`: session token, server time, polling hints, and feature flags.
+- `RunHeartbeatRequest`: session token, version, status, capacity, and current capability fingerprint.
+- `RunHeartbeatResponse`: accepted status, next heartbeat interval, and optional capability refresh request.
+- `RunCapabilityReport`: capability names and compact fingerprint metadata.
+- `RunCapacityReport`: max jobs, active jobs, queued jobs, and local resource summary.
+
+## Rules
+
+- Control payloads must be small.
+- Control must not carry logs, artifact chunks, or long job result bodies.
+- Control must have priority over job execution, log upload, and artifact transfer.
+- Heartbeat capacity summaries must remain metadata-only and must not mention or carry heavy channel payloads.
+
+## Deferred Channels
+
+Durable log ingest, artifact chunk transfer, and the optional game client bridge remain separate channels. The job channel is separate from control and uses `/api/v1/run/jobs/*` routes.