Breaking: require snapshots to be created synchronously

Ref Level/community#118.

Author: vweevers

README.md

@@ -282,8 +282,6 @@ Get a value from the database by `key`. The optional `options` object may contai
 
 Returns a promise for the value. If the `key` was not found then the value will be `undefined`.
 
-If the database indicates support of snapshots via `db.supports.snapshots` then `db.get()` _should_ read from a snapshot of the database, created at the time `db.get()` was called. This means it should not see the data of simultaneous write operations. However, this is currently not verified by the [abstract test suite](#test-suite).
-
 ### `db.getMany(keys[, options])`
 
 Get multiple values from the database by an array of `keys`. The optional `options` object may contain:
@@ -293,8 +291,6 @@ Get multiple values from the database by an array of `keys`. The optional `optio
 
 Returns a promise for an array of values with the same order as `keys`. If a key was not found, the relevant value will be `undefined`.
 
-If the database indicates support of snapshots via `db.supports.snapshots` then `db.getMany()` _should_ read from a snapshot of the database, created at the time `db.getMany()` was called. This means it should not see the data of simultaneous write operations. However, this is currently not verified by the [abstract test suite](#test-suite).
-
 ### `db.put(key, value[, options])`
 
 Add a new entry or overwrite an existing entry. The optional `options` object may contain:
@@ -1394,12 +1390,16 @@ The default `_close()` is an async noop. In native implementations (native addon
 
 Get a value by `key`. The `options` object will always have the following properties: `keyEncoding` and `valueEncoding`. Must return a promise. If an error occurs, reject the promise. Otherwise resolve the promise with the value. If the `key` was not found then use `undefined` as value.
 
+If the database indicates support of snapshots via `db.supports.snapshots` then `db._get()` must read from a snapshot of the database. That snapshot (or similar mechanism) must be created synchronously when `db._get()` is called, before asynchronously reading the value. This means it should not see the data of write operations that are scheduled immediately after `db._get()`.
+
 The default `_get()` returns a promise for an `undefined` value. It must be overridden.
 
 ### `db._getMany(keys, options)`
 
 Get multiple values by an array of `keys`. The `options` object will always have the following properties: `keyEncoding` and `valueEncoding`. Must return a promise. If an error occurs, reject the promise. Otherwise resolve the promise with an array of values. If a key does not exist, set the relevant value to `undefined`.
 
+Snapshot behavior of `db._getMany()` must be the same as described for `db._get()` above.
+
 The default `_getMany()` returns a promise for an array of values that is equal in length to `keys` and is filled with `undefined`. It must be overridden.
 
 ### `db._put(key, value, options)`

UPGRADING.md

@@ -16,6 +16,7 @@ This document describes breaking changes and how to upgrade. For a complete list
     - [2.1. Promises all the way](#21-promises-all-the-way)
     - [2.2. Ticks](#22-ticks)
     - [2.3. A new way to abort iterator work](#23-a-new-way-to-abort-iterator-work)
+    - [2.4. Snapshots must be synchronous](#24-snapshots-must-be-synchronous)
 - [1.0.0](#100)
   - [1. API parity with `levelup`](#1-api-parity-with-levelup)
     - [1.1. New: promises](#11-new-promises)
@@ -211,6 +212,10 @@ _This section is incomplete._
 
 Closing an iterator now aborts work, if supported by implementation. The undocumented `abortOnClose` option of iterators (added as a workaround for `many-level`) has been removed in favor of AbortSignal.
 
+#### 2.4. Snapshots must be synchronous
+
+If an implementations indicates support of snapshots via `db.supports.snapshots` then the `db._get()` and `db._getMany()` methods are now required to synchronously create their snapshot, rather than asynchronously. For details, please see the [README](./README.md#db_getkey-options). This is a documentation-only change because the abstract test suite cannot verify it.
+
 ## 1.0.0
 
 **Introducing `abstract-level`: a fork of [`abstract-leveldown`](https://github.com/Level/abstract-leveldown) that removes the need for [`levelup`](https://github.com/Level/levelup), [`encoding-down`](https://github.com/Level/encoding-down) and more. An `abstract-level` database is a complete solution that doesn't need to be wrapped. It has the same API as `level(up)` including encodings, promises and events. In addition, implementations can now choose to use Uint8Array instead of Buffer. Consumers of an implementation can use both. Sublevels are builtin.**