Service cleanups...

runtime/vm/service/service.md

-# Dart VM Service Protocol 0.0
+# Dart VM Service Protocol 1.0 (Draft 1)
 
-This document describes _version 0.0_ of the Dart VM Service Protocol.
-This protocol is used to communicate with a running Dart Virtual
-Machine.
+This document describes _draft 1_ of _version 1.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
 here.
 
 The Service Protocol is based on JSON-RPC 2.0
-(http://www.jsonrpc.org/specification).  The Service Protocol has been
+(http://www.jsonrpc.org/specification). The Service Protocol has been
 extended to support pushing _events_ to the client, which is
 apparently outside the scope of the JSON-RPC specification.
 
 **Table of Contents**
 
 - [RPCs, Requests, and Responses](#rpcs-requests-and-responses)
 - [Events](#events)
 - [Types](#types)
 - [IDs and Names](#ids-and-names)
 - [Versioning](#versioning)
@@ skipping 17 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)
         - [TypeArguments](#typearguments)
         - [Response](#response)
         - [Version](#version)
         - [VM](#vm)
 - [Revision History](#revision-history)
 
 ## RPCs, Requests, and Responses
 
-An RPC request is a JSON object sent to the server.  Here is an
+An RPC request is a JSON object sent to the server. Here is an
 example [getVersion](#getversion) request:
 
 ```
 {
   "jsonrpc": "2.0",
   "method": "getVersion",
   "params": {},
   "id": "1"
 }
 ```
 
-Currently the _id_ property must be a string.  The Service Protocol
+Currently the _id_ property must be a string. The Service Protocol
 optionally accepts requests without the _jsonprc_ property.
 
-An RPC response is a JSON object (http://json.org/).  The response always specifies an
-_id_ property to pair it with the corresponding request.  If the RPC
+An RPC response is a JSON object (http://json.org/). The response always specifies an
+_id_ property to pair it with the corresponding request. If the RPC
 was successful, the _result_ property provides the result.
 
 Here is an example response for our [getVersion](#getversion) request above:
 
 ```
 {
   "json-rpc": "2.0",
   "result": {
     "type": "Version",
-    "major": 0,
+    "major": 1,
     "minor": 0
   }
   "id": "1"
 }
 ```
 
 Parameters for RPC requests are always provided as _named_ parameters.
 The JSON-RPC spec provides for _positional_ parameters as well, but they
 are not supported by the Dart VM.
 
 By convention, every response returned by the Service Protocol is a subtype
 of [Response](#response) and provides a _type_ paramters which can be used
-to distinguish the exact return type.  In the example above, the
+to distinguish the exact return type. In the example above, the
 [Version](#version) type is returned.
 
 Here is an example [streamListen](#streamlisten) request which provides
 a parameter:
 
 ```
 {
   "jsonrpc": "2.0",
   "method": "streamListen",
   "params": {
     "streamId": "GC",
   },
   "id": "2"
 }
 ```
 
 <a name="rpc-error"></a>
 When an RPC encounters an error, it is provided in the _error_
-property of the response object.  JSON-RPC errors always provide
+property of the response object. JSON-RPC errors always provide
 _code_, _message_, and _data_ properties.
 
 Here is an example error response for our [streamListen](#streamlisten)
-request above.  This error would be generated if we were attempting to
+request above. This error would be generated if we were attempting to
 subscribe to the _GC_ stream multiple times from the same client.
 
 ```
 {
   "json-rpc": "2.0",
   "error": {
     "code": 103,
     "message": "Stream already subscribed",
     "data": {
       "details": "The stream 'GC' is already subscribed"
@@ skipping 14 matching lines @@
 103 | Stream already subscribed | The client is already subscribed to the specified _streamId_
 104 | Stream not subscribed | The client is not subscribed to the specified _streamId_
 
 
 
 
 ## Events
 
 By using the [streamListen](#streamlisten) and [streamCancel](#streamcancel) RPCs, a client may
 request to be notified when an _event_ is posted to a specific
-_stream_ in the VM.  Every stream has an associated _stream id_ which
+_stream_ in the VM. Every stream has an associated _stream id_ which
 is used to name that stream.
 
-Each stream provides access to certain kinds of events.  For example the _Isolate_ stream provides
-access to events pertaining to isolate births, deaths, and name changes.  See [streamListen](#streamlisten)
+Each stream provides access to certain kinds of events. For example the _Isolate_ stream provides
+access to events pertaining to isolate births, deaths, and name changes. See [streamListen](#streamlisten)
 for a list of the well-known stream ids and their associated events.
 
 Events arrive asynchronously over the WebSocket and always have the
 _streamId_ and _event_ properties:
 
 ```
 {
   "event": {
     "type": "Event",
     "kind": "IsolateExit",
     "isolate": {
       "type": "@Isolate",
       "id": "isolates/33",
       "number": "51048743613",
       "name": "worker-isolate"
     }
   }
   "streamId": "Isolate"
 }
 ```
 
 It is considered a _backwards compatible_ change to add a new type of event to an existing stream.
 Clients should be written to handle this gracefully.
 
 
 ## Types
 
 By convention, every result and event provided by the Service Protocol
 is a subtype of [Response](#response) and has the _type_ property.
-This allows the client to distinguish different kinds of responses.  For example,
+This allows the client to distinguish different kinds of responses. For example,
 information about a Dart function is returned using the [Function](#function) type.
 
 If the type of a response begins with the _@_ character, then that
-response is a _reference_.  If the type name of a response does not
-begin with the _@_ character, it is the an _object_.  A reference is
+response is a _reference_. If the type name of a response does not
+begin with the _@_ character, it is the an _object_. A reference is
 intended to be a subset of an object which provides enough information
 to generate a reasonable looking reference to the object.
 
 For example, an [@Isolate](#isolate) reference has the _type_, _id_, _name_ and
 _number_ properties:
 
 ```
   "result": {
     "type": "@Isolate",
     "id": "isolates/33",
@@ skipping 14 matching lines @@
     "entry": ...
     "heaps": ...
      ...
   }
 ```
 
 ## IDs and Names
 
 Many responses returned by the Service Protocol have an _id_ property.
 This is an identifier used to request an object from an isolate using
-the [getObject](#getobject) RPC.  If two responses have the same _id_ then they
-refer to the same object.  The converse is not true: the same object
+the [getObject](#getobject) RPC. If two responses have the same _id_ then they
+refer to the same object. The converse is not true: the same object
 may sometimes be returned with two different values for _id_.
 
 The _id_ property should be treated as an opaque string by the client:
 it is not meant to be parsed.
 
 An id can be either _temporary_ or _fixed_:
 
-* A _temporary_ id can expire over time.  The VM allocates certain ids
+* A _temporary_ id can expire over time. The VM allocates certain ids
   in a ring which evicts old ids over time.
 
 * A _fixed_ id will never expire, but the object it refers to may
-  be collected.  The VM uses fixed ids for objects like scripts,
+  be collected. The VM uses fixed ids for objects like scripts,
   libraries, and classes.
 
 If an id is fixed, the _fixedId_ property will be true. If an id is temporary
 the _fixedId_ property will be omitted.
 
-Sometimes a temporary id may expire.  In this case, some RPCs may return
+Sometimes a temporary id may expire. In this case, some RPCs may return
 an _Expired_ [Sentinel](#sentinel) to indicate this.
 
 The object referred to by an id may be collected by the VM's garbage
-collector.  In this case, some RPCs may return a _Collected_ [Sentinel](#sentinel)
+collector. In this case, some RPCs may return a _Collected_ [Sentinel](#sentinel)
 to indicate this.
 
-Many objects also have a _name_ property.  This is provided so that
+Many objects also have a _name_ property. This is provided so that
 objects can be displayed in a way that a Dart language programmer
-would find familiar.  Names are not unique.
+would find familiar. Names are not unique.
 
 ## Versioning
 
 The [getVersion](#getversion) RPC can be used to find the version of the protocol
-returned by a VM.  The _Version_ response has a major and a minor
+returned by a VM. The _Version_ response has a major and a minor
 version number:
 
 ```
   "result": {
     "type": "Version",
-    "major": 0,
+    "major": 1,
     "minor": 0
   }
 ```
 
 The major version number is incremented when the protocol is changed
-in a potentially _incompatible_ way.  An example of an incompatible
+in a potentially _incompatible_ way. An example of an incompatible
 change is removing a non-optional property from a result.
 
 The minor version number is incremented when the protocol is changed
-in a _backwards compatible_ way.  An example of a backwards compatible
+in a _backwards compatible_ way. An example of a backwards compatible
 change is adding a property to a result.
 
 Certain changes that would normally not be backwards compatible are
 considered backwards compatible for the purposes of versioning.
 Specifically, additions can be made to the [EventKind](#eventkind) and
 [InstanceKind](#instancekind) enumerated types and the client must
-handle this gracefully.  See the notes on these enumerated types for more
+handle this gracefully. See the notes on these enumerated types for more
 information.
 
 ## Private RPCs, Types, and Properties
 
 Any RPC, type, or property which begins with an underscore is said to
-be _private_.  These RPCs, types, and fields can be changed at any
+be _private_. These RPCs, types, and fields can be changed at any
 time without changing major or minor version numbers.
 
 The intention is that the Service Protocol will evolve by adding
 private RPCs which may, over time, migrate to the public api as they
-become stable.  Some private types and properties expose VM specific
+become stable. Some private types and properties expose VM specific
 implementation state and will never be appropriate to add to
 the public api.
 
 ## Public RPCs
 
 The following is a list of all public RPCs supported by the Service Protocol.
 
 An RPC is described using the following format:
 
 ```
 ReturnType methodName(parameterType1 parameterName1,
                       parameterType2, parameterName2,
                       ...)
 ```
 
 If an RPC says it returns type _T_ it may actually return _T_ or any
-[subtype](#public-types) of _T_.  For example, an
+[subtype](#public-types) of _T_. For example, an
 RPC which is declared to return [@Instance](#instance) may actually
 return [@Int](#int).
 
 If an RPC can return one or more independent types, this is indicated
 with the vertical bar:
 
 ```
 ReturnType1|ReturnType2
 ```
 
 Any RPC may return an _error_ response as [described above](#rpc-error).
 
-Some parameters are optional.  This is indicated by the text
+Some parameters are optional. This is indicated by the text
 _[optional]_ following the parameter name:
 
 ```
 ReturnType methodName(parameterType parameterName [optional)
 ```
 
 A description of the return types and parameter types is provided
 in the section on [public types](#public-types).
 
 ### addBreakpoint
@@ skipping 59 matching lines @@
 
 ### evaluateInFrame
 
 ```
 @Instance|@Error evaluateInFrame(string isolateId,
                                  int frameIndex,
                                  string expression)
 ```
 
 The _evaluateInFrame_ RPC is used to evaluate an expression in the
-context of a particular stack frame.  _frameIndex_ is the index of the
+context of a particular stack frame. _frameIndex_ is the index of the
 desired [Frame](#frame), with an index of _0_ indicating the top (most
 recent) frame.
 
 If an error occurs while evaluating the expression, an [@Error](#error)
 reference will be returned.
 
 If the expression is evaluated successfully, an [@Instance](#instance)
 reference will be returned.
 
 ### getFlagList
@@ skipping 37 matching lines @@
 If the object handle has not expired and the object has not been
 collected, then an [Object](#object) will be returned.
 
 ### getStack
 
 ```
 Stack getStack(string isolateId)
 ```
 
 The _getStack_ RPC is used to retrieve the current execution stack and
-message queue for an isolate.  The isolate does not need to be paused.
+message queue for an isolate. The isolate does not need to be paused.
 
 See [Stack](#stack).
 
 ### getVersion
 
 ```
 Version getVersion()
 ```
 
 The _getVersion_ RPC is used to determine what version of the Service Protocol is served by a VM.
 
 See [Version](#version).
 
 ### getVM
 
 ```
 VM getVM()
 ```
 
 The _getVM_ RPC returns global information about a Dart virtual machine.
 
 See [VM](#vm).
 
 ### pause
 
 ```
 Success pause(string isolateId)
 ```
 
-The _pause_ RPC is used to interrupt a running isolate.  The RPC enqueues the interrupt request and potentially returns before the isolate is paused.
+The _pause_ RPC is used to interrupt a running isolate. The RPC enqueues the interrupt request and potentially returns before the isolate is paused.
 
 When the isolate is paused an event will be sent on the _Debug_ stream.
 
 See [Success](#success).
 
 ### removeBreakpoint
 
 ```
 Success removeBreakpoint(string isolateId,
                          string breakpointId)
@@ skipping 64 matching lines @@
 subscribed) error code is returned.
 
 See [Success](#success).
 
 ### streamListen
 
 ```
 Success streamListen(string streamId)
 ```
 
-The _streamListen_ RPC subscribes to a stream in the VM.  Once
+The _streamListen_ RPC subscribes to a stream in the VM. Once
 subscribed, the client will begin receiving events from the stream.
 
 If the client is not subscribed to the stream, the _103_ (Stream already
 subscribed) error code is returned.
 
 The _streamId_ parameter may have the following published values:
 
 streamId | event types provided
 -------- | -----------
 Isolate | IsolateStart, IsolateExit, IsolateUpdate
@@ skipping 25 matching lines @@
 ```
 class T {
   string name;
   int count;
   ...
 }
 ```
 
 This describes a JSON object type _T_ with some set of expected properties.
 
-Types are organized into an inheritance hierarchy.  If type _T_
+Types are organized into an inheritance hierarchy. If type _T_
 extends type _S_...
 
 ```
 class S {
   string a;
 }
 
 class T extends S {
   string b;
 }
 ```
 
 ...then that means that all properties of _S_ are also present in type
-_T_.  In the example above, type _T_ would have the expected
+_T_. In the example above, type _T_ would have the expected
 properties _a_ and _b_.
 
 If a property has an _Array_ type, it is written with brackets:
 
 ```
   PropertyType[] arrayProperty;
 ```
 
 If a property is optional, it is suffixed with the text _[optional]_:
 
@@ skipping 111 matching lines @@
 
   // The location of this class in the source code.
   SourceLocation location [optional];
 
   // The superclass of this class, if any.
   @Class super [optional];
 
   // A list of interface types for this class.
   @Type[] interfaces;
 
-  // A list of fields in this class.  Does not include fields from
+  // A list of fields in this class. Does not include fields from
   // superclasses.
   @Field[] fields;
 
-  // A list of functions in this class.  Does not include functions
+  // A list of functions in this class. Does not include functions
   // from superclasses.
   @Function[] functions;
 
   // A list of subclasses of this class.
   @Class[] subclasses;
 }
 ```
 
 A _Class_ provides information about a Dart language class.
 
@@ skipping 51 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
+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.
   Frame topFrame [optional];
 
   // The exception associated with this event, if this is a
   // PauseException event.
   @Instance exception [optional];
 }
 ```
 
-An _Event_ is an asynchronous notification from the VM.  It is delivered
+An _Event_ is an asynchronous notification from the VM. It is delivered
 only when the client has subscribed to an event stream using the
 [streamListen](#streamListen) RPC.
 
 For more information, see [events](#events).
 
 ### EventKind
 
 ```
 enum EventKind {
   // Notification that a new isolate has started.
@@ skipping 33 matching lines @@
 
   // A breakpoint has been removed.
   BreakpointRemoved,
 
   // A garbage collection event.
   GC
 }
 ```
 
 Adding new values to _EventKind_ is considered a backwards compatible
-change.  Clients should ignore unrecognized events.
+change. Clients should ignore unrecognized events.
 
 ### Field
 
 ```
 class @Field extends @Object {
   // The name of this field.
   string name;
 
   // The owner of this field, which can be either a Library or a
   // Class.
@@ skipping 140 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)
   string valueAsString [optional];
 
-  // The valueAsString for String references may be truncated.  If so,
+  // The valueAsString for String references may be truncated. If so,
   // this property is added with the value 'true'.
   bool valueAsStringIsTruncated [optional];
 
   // The length of a List instance.
   //
   // Provided for instance kinds:
   //   List
   int length [optional];
 
   // The name of a Type instance.
@@ skipping 16 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];
 
-  // The valueAsString for String references may be truncated.  If so,
+  // The valueAsString for String references may be truncated. If so,
   // this property is added with the value 'true'.
   bool valueAsStringIsTruncated [optional];
 
   // The length of a List instance.
   //
   // Provided for instance kinds:
   //   List
   int length [optional];
 
   // The name of a Type instance.
@@ skipping 14 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 referent of a TypeRef instance.
+  // - or -
+  // 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 targetType [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 17 matching lines @@
 
   // An instance of the Dart class double.
   Double,
 
   // An instance of the Dart class int.
   Int,
 
   // An instance of the Dart class String.
   String,
 
-  // An instance of the built-in VM List implementation.  User-defined
+  // An instance of the built-in VM List implementation. User-defined
   // Lists will be PlainInstance.
   List,
 
-  // An instance of the built-in VM Map implementation.  User-defined
+  // An instance of the built-in VM Map implementation. User-defined
   // Maps will be PlainInstance.
   Map,
 
-  // An instance of the built-in VM Closure implementation.  User-defined
+  // An instance of the built-in VM Closure implementation. User-defined
   // Closures will be PlainInstance.
   Closure,
 
   // An instance of the Dart class MirrorReference.
   MirrorReference,
 
   // An instance of the Dart class WeakProperty.
   WeakProperty,
 
   // An instance of the Dart class Type
   Type,
 
   // An instance of the Dart class TypeParamer
   TypeParameter,
 
   // An instance of the Dart class TypeRef
   TypeRef,
 
   // An instance of the Dart class BoundedType
   BoundedType,
 }
 ```
 
 Adding new values to _InstanceKind_ is considered a backwards
-compatible change.  Clients should treat unrecognized instance kinds
+compatible change. Clients should treat unrecognized instance kinds
 as _PlainInstance_.
 
 ### Isolate
 
 ```
 class @Isolate extends Response {
   // The id which is passed to the getIsolate RPC to load this isolate.
   string id;
 
-  // A numeric id for this isolate, represented as a string.  Unique.
+  // A numeric id for this isolate, represented as a string. Unique.
   string number;
 
-  // A name identifying this isolate.  Not guaranteed to be unique.
+  // A name identifying this isolate. Not guaranteed to be unique.
   string name;
 }
 ```
 
 _@Isolate_ is a reference to an _Isolate_ object.
 
 ```
 class Isolate extends Response {
   // The id which is passed to the getIsolate RPC to reload this
   // isolate.
   string id;
 
-  // A numeric id for this isolate, represented as a string.  Unique.
+  // A numeric id for this isolate, represented as a string. Unique.
   string number;
 
-  // A name identifying this isolate.  Not guaranteed to be unique.
+  // A name identifying this isolate. Not guaranteed to be unique.
   string name;
 
   // The time that the VM started in milliseconds since the epoch.
   //
   // Suitable to pass to DateTime.fromMillisecondsSinceEpoch.
   int startTime;
 
   // The entry function for this isolate.
   @Function entry [optional];
 
   // The number of live ports for this isolate.
   int livePorts;
 
   // Will this isolate pause when exiting?
   bool pauseOnExit;
 
-  // The last pause event delivered to the isolate.  If the isolate is
+  // The last pause event delivered to the isolate. If the isolate is
   // running, this will be a resume event.
   Event pauseEvent;
 
   // The error that is causing this isolate to exit, if applicable.
   Error error [optional];
 
   // The root library for this isolate.
   @Library rootLib;
 
   // A list of all libraries for this isolate.
@@ skipping 65 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 26 matching lines @@
   string valueAsString;
 }
 ```
 
 A _Null_ object represents the Dart language value null.
 
 ### Object
 
 ```
 class @Object extends Response {
-  // A unique identifier for an Object.  Passed to the
+  // A unique identifier for an Object. Passed to the
   // getObject RPC to load this Object.
   string id
 }
 ```
 
 _@Object_ is a reference to a _Object_.
 
 ```
 class Object extends Response {
-  // A unique identifier for an Object.  Passed to the
+  // 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?
   SentinelKind kind;
 
   // A reasonable string representation of this sentinel.
   string valueAsString;
 }
 ```
 
 A _Sentinel_ is used to indicate that the normal response is not available.
 
 We use a _Sentinel_ instead of an [error](#errors) for these cases because
-they do not represent a problematic condition.  They are normal.
+they do not represent a problematic condition. They are normal.
 
 ### SentinelKind
 
 ```
 enum SentinelKind {
   // Indicates that the object referred to has been collected by the GC.
   Collected,
 
   // Indicates that an object id has expired.
   Expired,
 
   // Indicates that a variable or field has not been initialized.
   NotInitialized,
 
   // Indicates that a variable or field is in the process of being initialized.
   BeingInitialized,
 
   // Indicates that a variable has been eliminated by the optimizing compiler.
   OptimizedOut,
 
   // Reserved for future use.
   Free,
 }
 ```
 
 A _SentinelKind_ is used to distinguish different kinds of _Sentinel_ objects.
 
 Adding new values to _SentinelKind_ is considered a backwards
-compatible change.  Clients must handle this gracefully.
+compatible change. Clients must handle this gracefully.
 
 ### Script
 
 ```
 class @Script extends @Object {
   // The uri from which this script was loaded.
   string uri;
 }
 ```
 
 _@Script_ is a reference to a _Script_.
 
 ```
 class Script extends Object {
   // The uri from which this script was loaded.
   string uri;
 
   // The library which owns this script.
   @Library library;
 
-  // The source code for this script.  For certain built-in scripts,
+  // The source code for this script. For certain built-in scripts,
   // this may be reconstructed without source comments.
   string source;
 
   // A table encoding a mapping from token position to line and column.
   int[][] tokenPosTable;
 }
 ```
 
 A _Script_ provides information about a Dart language script.
 
-The _tokenPosTable_ is an array of int arrays.  Each subarray
+The _tokenPosTable_ is an array of int arrays. Each subarray
 consists of a line number followed by _(tokenPos, columnNumber)_ pairs:
 
 > [lineNumber, (tokenPos, columnNumber)*]
 
 For example, a _tokenPosTable_ with the value...
 
 > [[1, 100, 5, 101, 8],[2, 102, 7]]
 
 ...encodes the mapping:
 
@@ skipping 73 matching lines @@
 ```
 
 A _TypeArguments_ object represents the type argument vector for some
 instantiated generic type.
 
 ### Response
 
 ```
 class Response {
   // Every response returned by the VM Service has the
-  // type property.  This allows the client distinguish
+  // type property. This allows the client distinguish
   // between different kinds of responses.
   string type;
 }
 ```
 
 Every non-error response returned by the Service Protocol extends _Response_.
 By using the _type_ property, the client can determine which [type](#types)
 of response has been provided.
 
 ### Version
@@ skipping 38 matching lines @@
 
   // A list of isolates running in the VM.
   @Isolate[] isolates
 }
 ```
 
 ## Revision History
 
 version | comments
 ------- | --------
-0.0 | draft
+1.0 draft 1 | initial revision