Updates based on OCI f2f last week

Signed-off-by: Doug Davis <dug@us.ibm.com>

Author: Doug Davis

runtime.md

@@ -2,18 +2,9 @@
 
 ## State
 
-An OCI compliant runtime MUST store container metadata on disk so that external tools can consume and act on this information.
-It is recommended that this data be stored in a temporary filesystem so that it can be removed on a system reboot.
-On Linux/Unix based systems the metadata MUST be stored under `/run/opencontainer/containers`.
-For non-Linux/Unix based systems the location of the root metadata directory is currently undefined.
-Within that directory there MUST be one directory for each container created, where the name of the directory MUST be the ID of the container.
-For example: for a Linux container with an ID of `173975398351`, there will be a corresponding directory: `/run/opencontainer/containers/173975398351`.
-Within each container's directory, there MUST be a JSON encoded file called `state.json` that contains the runtime state of the container.
-For example: `/run/opencontainer/containers/173975398351/state.json`.
-
-The `state.json` file MUST contain all of the following properties:
-
-* **`version`**: (string) is the OCF specification version used when creating the container.
+The state of a container MUST include, at least, the following propeties:
+
+* **`ociVersion`**: (string) is the OCI specification version used when creating the container.
 * **`id`**: (string) is the container's ID.
 This MUST be unique across all containers on this host.
 There is no requirement that it be unique across hosts.
@@ -23,35 +14,34 @@ This allows the hooks to perform cleanup and teardown logic after the runtime de
 * **`bundlePath`**: (string) is the absolute path to the container's bundle directory.
 This is provided so that consumers can find the container's configuration and root filesystem on the host.
 
-*Example*
-
+When serialized in JSON, the format MUST adhere to the following pattern:
 ```json
 {
-    "version": "0.2.0",
-    "id": "oc-container",
+    "ociVersion": "0.2.0",
+    "id": "oci-container1",
     "pid": 4422,
     "bundlePath": "/containers/redis"
 }
 ```
 
+See [Query State](#query-state) for information on retrieving the state of a container.
+
 ## Lifecycle
 The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
 
 1. OCI compliant runtime is invoked with a reference to the location of the bundle.
    How this reference is passed to the runtime is an implementation detail.
 2. The container's runtime environment MUST be created according to the configuration in `config.json` and `runtime.json`.
    Any updates to `config.json` or `runtime.json` after container is running MUST not affect the container.
-3. The container's `state.json` file MUST be written to the filesystem.
-4. The prestart hooks MUST be invoked by the runtime.
+3. The prestart hooks MUST be invoked by the runtime.
    If any prestart hook fails, then the container MUST be stopped and the lifecycle continues at step 8.
-5. The user specified process MUST be executed in the container.
-6. The poststart hooks MUST be invoked by the runtime.
+4. The user specified process MUST be executed in the container.
+5. The poststart hooks MUST be invoked by the runtime.
    If any poststart hook fails, then the container MUST be stopped and the lifecycle continues at step 8.
-7. Additional actions such as pausing the container, resuming the container or signaling the container MAY be performed using the runtime interface.
+6. Additional actions such as pausing the container, resuming the container or signaling the container MAY be performed using the runtime interface.
    The container MAY also error out, exit or crash.
-8. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
-9. The poststop hooks MUST be invoked by the runtime and errors, if any, MAY be logged.
-10. The `state.json` file associated with the container MUST be removed and the return code of the container's user specified process MUST be returned or logged.
+7. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
+8. The poststop hooks MUST be invoked by the runtime and errors, if any, MAY be logged.
 
 Note: The lifecycle is a WIP and it will evolve as we have more use cases and more information on the viability of a separate create phase.
 
@@ -63,9 +53,21 @@ OCI compliant runtimes MUST support the following operations, unless the operati
 In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation.
 Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging.
 
+### Query State
+
+`state <container-id>`
+
+This operation MUST generate an error if it is not provided the ID of a container.
+This operation MUST return the state of a container as specified in the [State](#state) section.
+
+
 ### Start
 
-Using the data in `config.json` and `runtime.json` files this operation MUST create a new container.
+`start <path-to-bundle> <container-id>`
+
+This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container.
+If the ID provided is not unique across all containers running on this host, or is not valid in any other way, the implementation MUST generate an error.
+Using the data in `config.json` and `runtime.json` files, that are in the bundle's directory, this operation MUST create a new container.
 This includes creating the relevant namespaces, resource limits, etc and configuring the appropriate capabilities for the container.
 A new process within the scope of the container  MUST be created as specified by the `config.json` file.
 The current working directory of the process MUST be set to the `cwd` field of the config.
@@ -75,27 +77,40 @@ Attempting to start an already running container MUST have no effect on the cont
 
 ### Stop
 
+`stop <container-id>`
+
+This operation MUST generate an error if it is not provided the container ID.
 This operation MUST stop and delete a running container.
 Stopping a container MUST stop all of the processes running within the scope of the container.
 Deleting a container MUST delete the associated namespaces and resources associated with the container.
+Once a container is deleted, its `id` MAY be used by subsequent containers.
 Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error.
 
 ### Pause
 
+`pause <container-id>`
+
+This operation MUST generate an error if it is not provided the container ID.
 This operation MUST suspend all processes that are running within the container.
 If the container is not running, either stopped or aleady paused, then this operation MUST have no effect on the container and MUST generate an error.
 
 ### Unpause
 
+`unpause <container-id>`
+
+This operation MUST generate an error if it is not provided the container ID.
 This operation MUST resume all processes that were previously paused via the `pause` operation.
 If the container is not paused then this operation MUST have no effect on the container and MUST generate an error.
 
 ### Exec
 
+`exec <container-id> <path-to-json>`
+
+This operation MUST generate an error if it is not provided the container ID and a path to the JSON describing the process to start.
 This operation MUST create a new process within the scope of the container.
 If the container is not running then this operation MUST have no effect on the container and MUST generate an error.
 Executing this operation multiple times MUST result in a new process each time.
-The specification of the new process MUST be done via a JSON encoded file matching the following format:
+The JSON describing the new process MUST adhere to the following format:
 ```
 {
     "terminal": true,