Summary
The WiredTiger timestamp API, is a mechanism for allowing applications to control visibility in the library. The timestamp is user controlled 64 bit number, and it's a requirement that timestamps are ordered for basic numerical checks.

WiredTiger never reserved specific values to hold special meanings, so the timestamp value is entirely owned by our users at the moment.

We currently overload the value 0 to mean both a globally visible thing, and a place where timestamps (or a particular timestamp) aren't in use.

We need to review our API to ensure the meaning of 0 is well defined, and that it is sensible.

APIs that should be included in the review are:

WT_CONNECTION::query_timestamp() /* Specifically regards to whether 0 and not set need to be distinguishable */
WT_CONNECTION::set_timestamp() /* As to whether setting this to 0 is different to not including the option */

WT_SESSION::create(cfg="import=[compare_timestamp]") /* As to whether setting this to 0 is different to not including the option */
WT_SESSION::query_timestamp() /* Specifically regards to whether 0 and not set need to be distinguishable */
WT_SESSION::flush_timestamp() /* As to whether setting this to 0 is different to not including the option */
WT_SESSION::verify(cfg="stable_timestamp") /* As to whether setting this to 0 is different to not including the option */
/* The following three functions set per-transaction timestamps. Check to see if there is a difference between not setting a timestamp, and explicitly setting it to 0 */
WT_SESSION::commit_transaction(cfg="commit_timestamp=X,durable_timestamp=X")
WT_SESSION::prepare_transaction()
WT_SESSION::timestamp_transaction()

Motivation
To gain confidence that the WiredTiger API is well defined. Other teams have not requested this.

• How likely is it that this use case or problem will occur?

This was somewhat motivated by WT-8366, so moderately likely.

• Is this issue urgent?

Only urgent because I don't like holes in our API

• Testing

Testing should be added, to ensure the API behaves as expected. This should happen via the WiredTiger API.

If any tests need to be changed due to this work, we should be very careful to test MongoDB and ensure the API change isn't relevant to them.

• Documentation update

Yes.