codify create handle algos + link issues

index.bs

@@ -61,8 +61,6 @@ different storage mechanism with a different API for such files. The entry point
 
 A <dfn export id="entry">file system entry</dfn> is either a [=file entry=] or a [=directory entry=].
 
-<!-- TODO(a-sully): Make these algorithms associated with a FileSystemHandle. -->
-
 Each [=/file system entry=] has an associated <dfn for="file system entry" id=entry-query-access>query access</dfn> algorithm, which takes "`read`"
 or "`readwrite`" <var ignore>mode</var> and returns a {{PermissionState}}. Unless specified
 otherwise it returns "{{PermissionState/denied}}". The algorithm is allowed to throw.
@@ -74,6 +72,8 @@ otherwise it returns "{{PermissionState/denied}}". The algorithm is allowed to t
 Note: Implementations that only implement this specification and not dependent specifications do not
 need to bother implementing [=/file system entry=]'s [=file system entry/query access=] and [=file system entry/request access=].
 
+Issue(101): Make access check algorithms associated with a FileSystemHandle.
+
 Each [=/file system entry=] has an associated <dfn for="file system entry" id=entry-name>name</dfn> (a [=string=]).
 
 A <dfn>valid file name</dfn> is a [=string=] that is not an empty string, is not equal to "." or "..",
@@ -179,7 +179,7 @@ run these steps:
     1. If |rootPath|.\[[|index|]] is not |childPath|.\[[|index|]], then
        [=/resolve=] |result| with null, and abort.
 
-  1. Let |relativePath| be an empty [=/list=].
+  1. Let |relativePath| be « ».
   1. [=list/For each=] |index| of [=the range=] from |rootPath|'s [=list/size=]
      to |rootPath|'s [=list/size=], exclusive,
      [=list/append=] |childPath|.\[[|index|]] to |relativePath|.
@@ -194,11 +194,11 @@ A <dfn export>file system locator</dfn> represents a potential location of a
 [=/file system entry=]. A [=/file system locator=] is either a [=file locator=]
 or a [=directory locator=].
 
-<!-- TODO(a-sully): Consider giving each locator a Storage Bucket. -->
-
 Each [=/file system locator=] has an associated <dfn export for="file system locator" id=locator-path>path</dfn> (a [=/file system path=]),
 a <dfn export for="file system locator" id=locator-kind>kind</dfn> (a {{FileSystemHandleKind}}), and
-a <dfn export for="file system locator" id=locator-root>root</dfn> (an opaque [=string=]).
+a <dfn export for="file system locator" id=locator-root>root</dfn> (a [=file system root=]).
+
+Issue(103): Consider giving each locator a Storage Bucket.
 
 A <dfn export>file locator</dfn> is a [=/file system locator=] whose
 [=file system locator/kind=] is {{FileSystemHandleKind/"file"}}.
@@ -312,7 +312,7 @@ Their [=deserialization steps=], given |serialized| and |value| are:
 1. If |serialized|.\[[Origin]] is not [=same origin=] with
    |value|'s [=relevant settings object=]'s [=environment settings object/origin=],
    then [=throw=] a "{{DataCloneError}}" {{DOMException}}.
-1. Set |value|'s [=FileSystemHandle/locator=] to |serialized|.\[[Locator]]
+1. Set |value|'s [=FileSystemHandle/locator=] to |serialized|.\[[Locator]].
 
 </div>
 
@@ -374,11 +374,11 @@ interface FileSystemFileHandle : FileSystemHandle {
 };
 </xmp>
 
-A {{FileSystemFileHandle}}'s associated [=FileSystemHandle/locator=]'s
+Note: A {{FileSystemFileHandle}}'s associated [=FileSystemHandle/locator=]'s
 [=file system locator/kind=] is {{FileSystemHandleKind/"file"}}.
 
 <div algorithm>
-To <dfn data-lt="creating a child FileSystemFileHandle">create a child FileSystemFileHandle</dfn>
+To <dfn data-lt="creating a child FileSystemFileHandle">create a child <code>FileSystemFileHandle</code></dfn>
 given a [=directory locator=] |parentLocator| and a [=file system entry/name=] |name|
 in a [=/Realm=] |realm|, run these steps:
 
@@ -396,7 +396,7 @@ in a [=/Realm=] |realm|, run these steps:
 </div>
 
 <div algorithm>
-To <dfn export data-lt="creating a new FileSystemFileHandle">create a new FileSystemFileHandle</dfn>
+To <dfn export data-lt="creating a new FileSystemFileHandle">create a new <code>FileSystemFileHandle</code></dfn>
 given a [=/file system root=] |root| and a [=/file system path=] |path|
 in a [=/Realm=] |realm|, run these steps:
 
@@ -426,15 +426,15 @@ in a [=/Realm=] |realm|, run these steps:
 The <dfn method for=FileSystemFileHandle>getFile()</dfn> method steps are:
 
 1. Let |result| be [=a new promise=].
-1. Let |entry| be the result of [=locating an entry=]
-   given [=this=]'s [=FileSystemHandle/locator=].
+1. Let |locator| be [=this=]'s [=FileSystemHandle/locator=].
 1. Run these steps [=in parallel=]:
+  1. Let |entry| be the result of [=locating an entry=] given |locator|.
   1. Let |access| be the result of running |entry|'s
      [=file system entry/query access=] given "`read`".
   1. If |access| is not "{{PermissionState/granted}}",
      [=/reject=] |result| with a "{{NotAllowedError}}" {{DOMException}} and abort.
 
-  1. If |entry| is `null`, [=/reject=] |result| with a
+  1. If |entry| is null, [=/reject=] |result| with a
      "{{NotFoundError}}" {{DOMException}} and abort.
   1. [=Assert=]: |entry| is a [=file entry=].
 
@@ -492,9 +492,9 @@ private file system=] via the {{FileSystemSyncAccessHandle}} interface.
 The <dfn method for=FileSystemFileHandle>createWritable(|options|)</dfn> method steps are:
 
 1. Let |result| be [=a new promise=].
-1. Let |entry| be the result of [=locating an entry=]
-   given [=this=]'s [=FileSystemHandle/locator=].
+1. Let |locator| be [=this=]'s [=FileSystemHandle/locator=].
 1. Run these steps [=in parallel=]:
+  1. Let |entry| be the result of [=locating an entry=] given |locator|.
   1. Let |access| be the result of running |entry|'s
      [=file system entry/request access=] given "`readwrite`".
      If that throws an exception, [=reject=] |result| with that exception and abort.
@@ -542,9 +542,9 @@ The <dfn method for=FileSystemFileHandle>createWritable(|options|)</dfn> method
 The <dfn method for=FileSystemFileHandle>createSyncAccessHandle()</dfn> method steps are:
 
 1. Let |result| be [=a new promise=].
-1. Let |entry| be the result of [=locating an entry=]
-   given [=this=]'s [=FileSystemHandle/locator=].
+1. Let |locator| be [=this=]'s [=FileSystemHandle/locator=].
 1. Run these steps [=in parallel=]:
+  1. Let |entry| be the result of [=locating an entry=] given |locator|.
   1. Let |access| be the result of running |entry|'s
      [=file system entry/request access=] given "`readwrite`".
      If that throws an exception, [=reject=] |result| with that exception and abort.
@@ -594,11 +594,11 @@ interface FileSystemDirectoryHandle : FileSystemHandle {
 };
 </xmp>
 
-A {{FileSystemDirectoryHandle}}'s associated [=FileSystemHandle/locator=]'s
+Note: A {{FileSystemDirectoryHandle}}'s associated [=FileSystemHandle/locator=]'s
 [=file system locator/kind=] is {{FileSystemHandleKind/"directory"}}.
 
 <div algorithm>
-To <dfn data-lt="creating a child FileSystemDirectoryHandle">create a child FileSystemDirectoryHandle</dfn>
+To <dfn data-lt="creating a child FileSystemDirectoryHandle">create a child <code>FileSystemDirectoryHandle</code></dfn>
 given a [=directory locator=] |parentLocator| and a [=file system entry/name=] |name|
 in a [=/Realm=] |realm|, run these steps:
 
@@ -616,7 +616,7 @@ in a [=/Realm=] |realm|, run these steps:
 </div>
 
 <div algorithm>
-To <dfn export data-lt="creating a new FileSystemDirectoryHandle">create a new FileSystemDirectoryHandle</dfn>
+To <dfn export data-lt="creating a new FileSystemDirectoryHandle">create a new <code>FileSystemDirectoryHandle</code></dfn>
 given a [=/file system root=] |root| and a [=/file system path=] |path|
 in a [=/Realm=] |realm|, run these steps:
 
@@ -698,11 +698,11 @@ and its async iterator |iterator|:
 1. Otherwise:
   1. [=set/Append=] |child|'s [=file system entry/name=] to |iterator|'s [=past results=].
   1. If |child| is a [=file entry=]:
-    1. Let |result| be the result of [=creating a child FileSystemFileHandle=]
+    1. Let |result| be the result of <a>creating a child <code>FileSystemFileHandle</code></a>
        with |handle|'s [=FileSystemHandle/locator=] and
        |child|'s [=file system entry/name=] in |handle|'s [=relevant Realm=].
   1. Otherwise:
-    1. Let |result| be the result of [=creating a child FileSystemDirectoryHandle=]
+    1. Let |result| be the result of <a>creating a child <code>FileSystemDirectoryHandle</code></a>
        with |handle|'s [=FileSystemHandle/locator=] and
        |child|'s [=file system entry/name=] in |handle|'s [=relevant Realm=].
   1. [=/Resolve=] |promise| with (|child|'s [=file system entry/name=], |result|).
@@ -740,10 +740,10 @@ The <dfn method for=FileSystemDirectoryHandle>getFileHandle(|name|, |options|)</
 1. Let |result| be [=a new promise=].
 1. Let |realm| be [=this=]'s [=relevant Realm=].
 1. Let |locator| be [=this=]'s [=FileSystemHandle/locator=].
-1. Let |entry| be the result of [=locating an entry=] given |locator|.
 1. Run these steps [=in parallel=]:
   1. If |name| is not a [=valid file name=], [=/reject=] |result| with a {{TypeError}} and abort.
 
+  1. Let |entry| be the result of [=locating an entry=] given |locator|.
   1. If |options|.{{FileSystemGetFileOptions/create}} is true:
     1. Let |access| be the result of running |entry|'s
        [=file system entry/request access=] given "`readwrite`".
@@ -764,7 +764,7 @@ The <dfn method for=FileSystemDirectoryHandle>getFileHandle(|name|, |options|)</
       1. If |child| is a [=directory entry=]:
         1. [=/Reject=] |result| with a "{{TypeMismatchError}}" {{DOMException}} and abort.
       1. [=/Resolve=] |result| with the result of
-         [=creating a child FileSystemFileHandle=] with |locator| and
+         <a>creating a child <code>FileSystemFileHandle</code></a> with |locator| and
          |child|'s [=file system entry/name=] in |realm| and abort.
   1. If |options|.{{FileSystemGetFileOptions/create}} is false:
     1. [=/Reject=] |result| with a "{{NotFoundError}}" {{DOMException}} and abort.
@@ -779,7 +779,7 @@ The <dfn method for=FileSystemDirectoryHandle>getFileHandle(|name|, |options|)</
 
      Issue(11): Better specify what possible exceptions this could throw.
   1. [=/Resolve=] |result| with the result of
-     [=creating a child FileSystemFileHandle=] with |locator| and
+     <a>creating a child <code>FileSystemFileHandle</code></a> with |locator| and
      |child|'s [=file system entry/name=] in |realm|.
 1. Return |result|.
 
@@ -814,10 +814,10 @@ The <dfn method for=FileSystemDirectoryHandle>getDirectoryHandle(|name|, |option
 1. Let |result| be [=a new promise=].
 1. Let |realm| be [=this=]'s [=relevant Realm=].
 1. Let |locator| be [=this=]'s [=FileSystemHandle/locator=].
-1. Let |entry| be the result of [=locating an entry=] given |locator|.
 1. Run these steps [=in parallel=]:
   1. If |name| is not a [=valid file name=], [=/reject=] |result| with a {{TypeError}} and abort.
 
+  1. Let |entry| be the result of [=locating an entry=] given |locator|.
   1. If |options|.{{FileSystemGetDirectoryOptions/create}} is true:
     1. Let |access| be the result of running |entry|'s
        [=file system entry/request access=] given "`readwrite`".
@@ -837,8 +837,8 @@ The <dfn method for=FileSystemDirectoryHandle>getDirectoryHandle(|name|, |option
       1. If |child| is a [=file entry=]:
         1. [=/Reject=] |result| with a "{{TypeMismatchError}}" {{DOMException}} and abort.
       1. [=/Resolve=] |result| with the result of
-         [=creating a child FileSystemDirectoryHandle=] with |locator| and
-         |child|'s [=file system entry/name=] in |realm| and abort.
+         <a>creating a child <code>FileSystemDirectoryHandle</code></a> with
+         |locator| and |child|'s [=file system entry/name=] in |realm| and abort.
   1. If |options|.{{FileSystemGetFileOptions/create}} is false:
     1. [=/Reject=] |result| with a "{{NotFoundError}}" {{DOMException}} and abort.
   1. Let |child| be a new [=directory entry=] whose [=query access=] and [=request access=]
@@ -851,8 +851,8 @@ The <dfn method for=FileSystemDirectoryHandle>getDirectoryHandle(|name|, |option
 
      Issue(11): Better specify what possible exceptions this could throw.
   1. [=/Resolve=] |result| with the result of
-     [=creating a child FileSystemDirectoryHandle=] with |locator| and
-     |child|'s [=file system entry/name=] in |realm|.
+     <a>creating a child <code>FileSystemDirectoryHandle</code></a> with
+     |locator| and |child|'s [=file system entry/name=] in |realm|.
 1. Return |result|.
 
 </div>
@@ -881,11 +881,11 @@ The <dfn method for=FileSystemDirectoryHandle>getDirectoryHandle(|name|, |option
 The <dfn method for=FileSystemDirectoryHandle>removeEntry(|name|, |options|)</dfn> method steps are:
 
 1. Let |result| be [=a new promise=].
-1. Let |entry| be the result of [=locating an entry=]
-   given [=this=]'s [=FileSystemHandle/locator=].
+1. Let |locator| be [=this=]'s [=FileSystemHandle/locator=].
 1. Run these steps [=in parallel=]:
   1. If |name| is not a [=valid file name=], [=/reject=] |result| with a {{TypeError}} and abort.
 
+  1. Let |entry| be the result of [=locating an entry=] given |locator|.
   1. Let |access| be the result of running |entry|'s
      [=file system entry/request access=] given "`readwrite`".
      If that throws an exception, [=reject=] |result| with that exception and abort.
@@ -1541,8 +1541,8 @@ The <dfn method for=StorageManager>getDirectory()</dfn> method steps are:
   1. Set |map|["root"] to |dir|.
 
 1. Let |root| be an [=implementation-defined=] opaque [=string=].
-1. Let |path| be an empty [=/list=].
-1. Let |handle| be the result of [=creating a new FileSystemDirectoryHandle=]
+1. Let |path| be « ».
+1. Let |handle| be the result of <a>creating a new <code>FileSystemDirectoryHandle</code></a>.
    given |root| and |path| in the [=current realm=].
 
   Note: |root| might include relevant identifying information such as the