Document per-item versions using @since gates

.github/workflows/main.yml

@@ -11,4 +11,4 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
-    - uses: WebAssembly/wit-abi-up-to-date@v17
+    - uses: WebAssembly/wit-abi-up-to-date@v21

imports.md

@@ -2,19 +2,19 @@
 <ul>
 <li>Imports:
 <ul>
-<li>interface <a href="#wasi:random_random_0.2.0"><code>wasi:random/[email protected]</code></a></li>
-<li>interface <a href="#wasi:random_insecure_0.2.0"><code>wasi:random/[email protected]</code></a></li>
-<li>interface <a href="#wasi:random_insecure_seed_0.2.0"><code>wasi:random/[email protected]</code></a></li>
+<li>interface <a href="#wasi_random_random_0_2_0"><code>wasi:random/[email protected]</code></a></li>
+<li>interface <a href="#wasi_random_insecure_0_2_0"><code>wasi:random/[email protected]</code></a></li>
+<li>interface <a href="#wasi_random_insecure_seed_0_2_0"><code>wasi:random/[email protected]</code></a></li>
 </ul>
 </li>
 </ul>
-<h2><a name="wasi:random_random_0.2.0">Import interface wasi:random/[email protected]</a></h2>
+<h2><a name="wasi_random_random_0_2_0"></a>Import interface wasi:random/[email protected]</h2>
 <p>WASI Random is a random data API.</p>
 <p>It is intended to be portable at least between Unix-family platforms and
 Windows.</p>
 <hr />
 <h3>Functions</h3>
-<h4><a name="get_random_bytes"><code>get-random-bytes: func</code></a></h4>
+<h4><a name="get_random_bytes"></a><code>get-random-bytes: func</code></h4>
 <p>Return <code>len</code> cryptographically-secure random or pseudo-random bytes.</p>
 <p>This function must produce data at least as cryptographically secure and
 fast as an adequately seeded cryptographically-secure pseudo-random
@@ -27,27 +27,27 @@ must omit this function, rather than implementing it with deterministic
 data.</p>
 <h5>Params</h5>
 <ul>
-<li><a name="get_random_bytes.len"><code>len</code></a>: <code>u64</code></li>
+<li><a name="get_random_bytes.len"></a><code>len</code>: <code>u64</code></li>
 </ul>
 <h5>Return values</h5>
 <ul>
 <li><a name="get_random_bytes.0"></a> list&lt;<code>u8</code>&gt;</li>
 </ul>
-<h4><a name="get_random_u64"><code>get-random-u64: func</code></a></h4>
+<h4><a name="get_random_u64"></a><code>get-random-u64: func</code></h4>
 <p>Return a cryptographically-secure random or pseudo-random <code>u64</code> value.</p>
 <p>This function returns the same type of data as <a href="#get_random_bytes"><code>get-random-bytes</code></a>,
 represented as a <code>u64</code>.</p>
 <h5>Return values</h5>
 <ul>
 <li><a name="get_random_u64.0"></a> <code>u64</code></li>
 </ul>
-<h2><a name="wasi:random_insecure_0.2.0">Import interface wasi:random/[email protected]</a></h2>
+<h2><a name="wasi_random_insecure_0_2_0"></a>Import interface wasi:random/[email protected]</h2>
 <p>The insecure interface for insecure pseudo-random numbers.</p>
 <p>It is intended to be portable at least between Unix-family platforms and
 Windows.</p>
 <hr />
 <h3>Functions</h3>
-<h4><a name="get_insecure_random_bytes"><code>get-insecure-random-bytes: func</code></a></h4>
+<h4><a name="get_insecure_random_bytes"></a><code>get-insecure-random-bytes: func</code></h4>
 <p>Return <code>len</code> insecure pseudo-random bytes.</p>
 <p>This function is not cryptographically secure. Do not use it for
 anything related to security.</p>
@@ -56,27 +56,27 @@ implementations are encouraged to return evenly distributed values with
 a long period.</p>
 <h5>Params</h5>
 <ul>
-<li><a name="get_insecure_random_bytes.len"><code>len</code></a>: <code>u64</code></li>
+<li><a name="get_insecure_random_bytes.len"></a><code>len</code>: <code>u64</code></li>
 </ul>
 <h5>Return values</h5>
 <ul>
 <li><a name="get_insecure_random_bytes.0"></a> list&lt;<code>u8</code>&gt;</li>
 </ul>
-<h4><a name="get_insecure_random_u64"><code>get-insecure-random-u64: func</code></a></h4>
+<h4><a name="get_insecure_random_u64"></a><code>get-insecure-random-u64: func</code></h4>
 <p>Return an insecure pseudo-random <code>u64</code> value.</p>
 <p>This function returns the same type of pseudo-random data as
 <a href="#get_insecure_random_bytes"><code>get-insecure-random-bytes</code></a>, represented as a <code>u64</code>.</p>
 <h5>Return values</h5>
 <ul>
 <li><a name="get_insecure_random_u64.0"></a> <code>u64</code></li>
 </ul>
-<h2><a name="wasi:random_insecure_seed_0.2.0">Import interface wasi:random/[email protected]</a></h2>
+<h2><a name="wasi_random_insecure_seed_0_2_0"></a>Import interface wasi:random/[email protected]</h2>
 <p>The insecure-seed interface for seeding hash-map DoS resistance.</p>
 <p>It is intended to be portable at least between Unix-family platforms and
 Windows.</p>
 <hr />
 <h3>Functions</h3>
-<h4><a name="insecure_seed"><code>insecure-seed: func</code></a></h4>
+<h4><a name="insecure_seed"></a><code>insecure-seed: func</code></h4>
 <p>Return a 128-bit value that may contain a pseudo-random value.</p>
 <p>The returned value is not required to be computed from a CSPRNG, and may
 even be entirely deterministic. Host implementations are encouraged to

wit/insecure-seed.wit

@@ -3,6 +3,7 @@ package wasi:[email protected];
 ///
 /// It is intended to be portable at least between Unix-family platforms and
 /// Windows.
+@since(version = 0.2.0)
 interface insecure-seed {
     /// Return a 128-bit value that may contain a pseudo-random value.
     ///
@@ -21,5 +22,6 @@ interface insecure-seed {
     /// This will likely be changed to a value import, to prevent it from being
     /// called multiple times and potentially used for purposes other than DoS
     /// protection.
+    @since(version = 0.2.0)
     insecure-seed: func() -> tuple<u64, u64>;
 }

wit/insecure.wit

@@ -3,6 +3,7 @@ package wasi:[email protected];
 ///
 /// It is intended to be portable at least between Unix-family platforms and
 /// Windows.
+@since(version = 0.2.0)
 interface insecure {
     /// Return `len` insecure pseudo-random bytes.
     ///
@@ -12,11 +13,13 @@ interface insecure {
     /// There are no requirements on the values of the returned bytes, however
     /// implementations are encouraged to return evenly distributed values with
     /// a long period.
+    @since(version = 0.2.0)
     get-insecure-random-bytes: func(len: u64) -> list<u8>;
 
     /// Return an insecure pseudo-random `u64` value.
     ///
     /// This function returns the same type of pseudo-random data as
     /// `get-insecure-random-bytes`, represented as a `u64`.
+    @since(version = 0.2.0)
     get-insecure-random-u64: func() -> u64;
 }

wit/random.wit

@@ -3,6 +3,7 @@ package wasi:[email protected];
 ///
 /// It is intended to be portable at least between Unix-family platforms and
 /// Windows.
+@since(version = 0.2.0)
 interface random {
     /// Return `len` cryptographically-secure random or pseudo-random bytes.
     ///
@@ -16,11 +17,13 @@ interface random {
     /// This function must always return fresh data. Deterministic environments
     /// must omit this function, rather than implementing it with deterministic
     /// data.
+    @since(version = 0.2.0)
     get-random-bytes: func(len: u64) -> list<u8>;
 
     /// Return a cryptographically-secure random or pseudo-random `u64` value.
     ///
     /// This function returns the same type of data as `get-random-bytes`,
     /// represented as a `u64`.
+    @since(version = 0.2.0)
     get-random-u64: func() -> u64;
 }

wit/world.wit

@@ -1,7 +1,13 @@
 package wasi:[email protected];
 
+@since(version = 0.2.0)
 world imports {
+    @since(version = 0.2.0)
     import random;
+
+    @since(version = 0.2.0)
     import insecure;
+
+    @since(version = 0.2.0)
     import insecure-seed;
 }