Revisit expected hash meaning

[adutra]

When an expected hash is provided for a commit, merge or transplant operation, the new storage model validates that the hash exists and is reachable from the current branch HEAD:

nessie/versioned/storage/store/src/main/java/org/projectnessie/versioned/storage/versionstore/BaseCommitHelper.java

Lines 136 to 142 in 795ba1d

	if (referenceHash.isPresent()) {
	ObjId referenceObjId = hashToObjId(referenceHash.get());
	if (!referenceObjId.equals(headId())) {
	RefMapping refMapping = new RefMapping(persist);
	e = refMapping.commitInChain(branch, head, referenceHash, emptyList());
	}
	}

However it does not enforce that the expected hash is the current HEAD. IOW, the operation may succeed even if extra, non-conflicting commits were added to the target branch in the meantime.

This is a bit in contradiction with the merge/transplant API docs for the expected hash parameter:

nessie/api/model/src/main/java/org/projectnessie/api/v2/doc/ApiDoc.java

Lines 78 to 80 in 46bf31b

	+ "The 'hash' commit must be reachable from the current HEAD of the branch.\n"
	+ "In this case 'hash' indicates the state of contents known to the client and serves to ensure that the "
	+ "operation is performed on the contents that the client expects.\n"

The commit docs OTOH are a bit closer to reality:

nessie/api/model/src/main/java/org/projectnessie/api/v2/doc/ApiDoc.java

Lines 58 to 60 in 46bf31b

	+ "If both 'name' and 'hash' are given, 'hash' must be reachable from the current HEAD of the branch.\n"
	+ "In this case 'hash' indicates the state of contents that should be used for validating incoming changes\n"
	+ "(commits / merges / transplants).\n"

It would be good to give users the ability to enforce that the expected hash is the current HEAD and/or revisit the docs for this parameter.

[adutra]

Currently only 2 endpoints enforce that the expected hash is the current HEAD: assignReference and deleteReference. Both throw HTTP 409 (Conflict) if that's not the case. The reported conflict type is Conflict.ConflictType#UNEXPECTED_HASH.