Service cleanups...

runtime/vm/service/service.md

 # Dart VM Service Protocol 0.0
 
 This document describes _version 0.0_ of the Dart VM Service Protocol.
 This protocol is used to communicate with a running Dart Virtual
 Machine.
 
 To use the Service Protocol, start the VM with the *--observe* flag.
 The VM will start a webserver which services protocol requests via WebSocket.
 It is possible to make HTTP (non-WebSocket) requests,
 but this does not allow access to VM _events_ and is not documented
@@ skipping 31 matching lines @@
         - [streamCancel](#streamcancel)
         - [streamListen](#streamlisten)
 - [Public Types](#public-types)
         - [BoundField](#boundfield)
         - [BoundVariable](#boundvariable)
         - [Breakpoint](#breakpoint)
         - [Class](#class)
         - [ClassList](#classlist)
         - [Code](#code)
         - [CodeKind](#codekind)
+        - [Context](#context)
+        - [ContextElement](#contextelement)
         - [Error](#error)
+        - [ErrorKind](#errorkind)
         - [Event](#event)
         - [EventKind](#eventkind)
         - [Field](#field)
         - [Flag](#flag)
         - [FlagList](#flaglist)
         - [Frame](#frame)
         - [Function](#function)
         - [Instance](#instance)
         - [Isolate](#isolate)
         - [Library](#library)
         - [LibraryDependency](#librarydependency)
-        - [ListElement](#listelement)
+        - [MapAssociation](#mapassociation)
         - [Message](#message)
         - [Null](#null)
         - [Object](#object)
         - [Sentinel](#sentinel)
         - [SentinelKind](#sentinelkind)
         - [Script](#script)
         - [SourceLocation](#sourcelocation)
         - [Stack](#stack)
         - [StepOption](#stepoption)
         - [Success](#success)
@@ skipping 787 matching lines @@
   int length;
 }
 ```
 
 ```
 class Context {
   // The number of variables in this context.
   int length;
 
   // The variables in this context object.
-  ListElement[] variables;
+  ContextElement[] variables;
 }
 ```
 
+### ContextElement
+
+```
+class ContextElement {
+  @Instance|Sentinel value;
+}
+```
+
 ### Error
 
 ```
 class @Error extends @Object {
+  // What kind of error is this?
+  ErrorKind kind;
+
   // A description of the error.
   string message;
 }
 ```
 
 _@Error_ is a reference to an _Error_.
 
 ```
 class Error extends Object {
+  // What kind of error is this?
+  ErrorKind kind;
+
   // A description of the error.
   string message;
 
   // If this error is due to an unhandled exception, this
   // is the exception thrown.
   @Instance exception [optional];
 
   // If this error is due to an unhandled exception, this
   // is the stacktrace object.
   @Instance stacktrace [optional];
 }
 ```
 
 An _Error_ represents a Dart language level error.  This is distinct from an
 [rpc error](#rpc-error).
 
-An error may occur when:
+### ErrorKind
 
-- The program has encountered an unhandled exception
-- The program has encountered a syntax error (or another Dart language error)
-- The program has encountered an unhandled erroneous condition in native code
-- The program has been terminated
+```
+enum ErrorKind {
+  // The isolate has encountered an unhandled Dart exception.
+  UnhandledException,
+
+  // The isolate has encountered a Dart language error in the program.
+  LanguageError,
+
+  // The isolate has encounted an internal error.  These errors should be
+  // reported as bugs.
+  InternalError,
+
+  // The isolate has been terminated by an external source.
+  TerminationError
+}
+```
 
 ### Event
 
 ```
 class Event extends Response {
   // What kind of event is this?
   EventKind kind;
 
   // The isolate with which this event is associated.
   @Isolate isolate;
 
-  // The breakpoint associated with this event, if applicable.
+  // The breakpoint which was added, removed, or resolved.
   //
   // This is provided for the event kinds:
   //   PauseBreakpoint
   //   BreakpointAdded
   //   BreakpointRemoved
   //   BreakpointResolved
   Breakpoint breakpoint [optional];
 
+  // The list of breakpoints at which we are currently paused
+  // for a PauseBreakpoint event.
+  //
+  // This list may be empty.  For example, while single-stepping, the
+  // VM sends a PauseBreakpoint event with no breakpoints.
+  //
+  // If there is more than one breakpoint set at the program position,
+  // then all of them will be provided.
+  //
+  // This is provided for the event kinds:
+  //   PauseBreakpoint
+  Breakpoint[] pauseBreakpoints [optional];
+
   // The top stack frame associated with this event, if applicable.
   //
   // This is provided for the event kinds:
   //   PauseBreakpoint
   //   PauseInterrupted
   //   PauseException
   //
   // For the Resume event, the top frame is provided at
   // all times except for the initial resume event that is delivered
   // when an isolate begins execution.
@@ skipping 213 matching lines @@
 
 A _Function_ represents a Dart language function.
 
 ### Instance
 
 ```
 class @Instance extends @Object {
   // What kind of instance is this?
   InstanceKind kind;
 
-  // Instance references include their class.
+  // Instance references always include their class.
   @Class class;
 
   // The value of this instance as a string.
   //
   // Provided for the instance kinds:
   //   Null (null)
   //   Bool (true or false)
   //   Double (suitable for passing to Double.parse())
   //   Int (suitable for passing to int.parse())
   //   String (value may be truncated)
@@ skipping 29 matching lines @@
 }
 ```
 
 _@Instance_ is a reference to an _Instance_.
 
 ```
 class Instance extends Object {
   // What kind of instance is this?
   InstanceKind kind;
 
-  // Instance references include their class.
+  // Instance references always include their class.
   @Class class;
 
   // The value of this instance as a string.
   //
   // Provided for the instance kinds:
   //   Bool (true or false)
   //   Double (suitable for passing to Double.parse())
   //   Int (suitable for passing to int.parse())
   //   String (value may be truncated)
   string valueAsString [optional];
@@ skipping 26 matching lines @@
   //   TypeParameter
   @Class parameterizedClass [optional];
 
   // The fields of this Instance.
   BoundField fields [optional];
 
   // The elements of a List instance.
   //
   // Provided for instance kinds:
   //   List
-  ListElement[] elements [optional];
+  @Instance|Sentinel[] elements [optional];
 
   // The elements of a List instance.
   //
   // Provided for instance kinds:
   //   Map
   MapAssociation[] associations [optional];
 
   // The function associated with a Closure instance.
   //
   // Provided for instance kinds:
@@ skipping 30 matching lines @@
   //   Type
   @TypeArguments typeArguments [optional];
 
   // The index of a TypeParameter instance.
   //
   // Provided for instance kinds:
   //   TypeParameter
   int parameterIndex [optional];
 
   // The type bounded by a BoundedType instance
-  // or
+  //
+  // The value will always be one of:
+  // Type, TypeRef, TypeParameter, BoundedType.
+  //
+  // Provided for instance kinds:
+  //   BoundedType
+  @Instance boundedType [optional];
+
   // The referent of a TypeRef instance.
   //
   // The value will always be one of:
   // Type, TypeRef, TypeParameter, BoundedType.
   //
   // Provided for instance kinds:
   //   BoundedType
   //   TypeRef
-  @Instance type [optional];
+  @Instance referentType [optional];
 
   // The bound of a TypeParameter or BoundedType.
   //
   // The value will always be one of:
   // Type, TypeRef, TypeParameter, BoundedType.
   //
   // Provided for instance kinds:
   //   BoundedType
   //   TypeParameter
   @Instance bound [optional];
@@ skipping 182 matching lines @@
   // The prefix of an 'as' import, or null.
   String prefix;
 
   // The library being imported or exported.
   @Library target;
 }
 ```
 
 A _LibraryDependency_ provides information about an import or export.
 
-### ListElement
-
-```
-class ListElement {
-  int index;
-  @Instance|Sentinel value;
-}
-```
-
 ### MapAssociation
 
 ```
 class MapAssociation {
   @Instance|Sentinel key;
   @Instance|Sentinel value;
 }
 ```
 
 ### Message
@@ skipping 42 matching lines @@
 _@Object_ is a reference to a _Object_.
 
 ```
 class Object extends Response {
   // A unique identifier for an Object.  Passed to the
   // getObject RPC to reload this Object.
   //
   // Some objects may get a new id when they are reloaded.
   string id;
 
-  // Every object has a corresponding Class in the VM.
-  @Class class;
+  // If an object is allocated in the Dart heap, it will have
+  // a corresponding class object.
+  //
+  // The class of a non-instance is not a Dart class, but is instead
+  // an internal vm object.
+  //
+  // Moving an Object into or out of the heap is considered a
+  // backwards compatible change for types other than Instance.
+  @Class class [optional];
 
   // The size of this object in the heap.
   //
-  // Note that the size can be zero for some objects.
-  int size;
+  // If an object is not heap-allocated, then this field is omitted.
+  //
+  // Note that the size can be zero for some objects.  In the current
+  // VM implementation, this occurs for small integers, which are
+  // stored entirely within their object pointers.
+  int size [optional];
 }
 ```
 
 An _Object_ is a  persistent object that is owned by some isolate.
 
 ### Sentinel
 
 ```
 class Sentinel extends Response {
   // What kind of sentinel is this?
@@ skipping 215 matching lines @@
   // A list of isolates running in the VM.
   @Isolate[] isolates
 }
 ```
 
 ## Revision History
 
 version | comments
 ------- | --------
 0.0 | draft