Refactor: javadocs and reduce warnings

bosk-core/src/main/java/io/vena/bosk/Bosk.java

@@ -933,7 +933,7 @@ public final boolean equals(Object obj) {
 			if (obj == null) {
 				return false;
 			}
-			if (!(obj instanceof @SuppressWarnings({"rawtypes"})Reference other)) {
+			if (!(obj instanceof Reference<?> other)) {
 				return false;
 			}
 

bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Demultiplexer.java

@@ -10,6 +10,9 @@
 
 import static java.util.Objects.requireNonNull;
 
+/**
+ * De-interlaces change stream events associated with different transactions.
+ */
 class Demultiplexer {
 	private final Map<TransactionID, List<ChangeStreamDocument<BsonDocument>>> transactionsInProgress = new ConcurrentHashMap<>();
 

bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/FormatMisconfigurationException.java

@@ -1,5 +1,9 @@
 package io.vena.bosk.drivers.mongo;
 
+/**
+ * Indicates that an error was found in a
+ * {@link MongoDriverSettings.DatabaseFormat DatabaseFormat} object.
+ */
 public class FormatMisconfigurationException extends IllegalArgumentException {
 	public FormatMisconfigurationException(String s) {
 		super(s);

bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Manifest.java

@@ -4,11 +4,21 @@
 import io.vena.bosk.drivers.mongo.MongoDriverSettings.DatabaseFormat;
 import java.util.Optional;
 
+/**
+ * Defines the format of the manifest document, which is stored in the database
+ * to describe the database contents.
+ */
 public record Manifest(
 	Integer version,
 	Optional<EmptyNode> sequoia,
 	Optional<PandoFormat> pando
 ) implements StateTreeNode {
+	public Manifest {
+		if (sequoia.isPresent() == pando.isPresent()) {
+			throw new IllegalArgumentException("Exactly one format (sequoia or pando) must be specified in manifest");
+		}
+	}
+
 	public record EmptyNode() implements StateTreeNode { }
 
 	public static Manifest forSequoia() {

bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/MongoDriver.java

@@ -8,6 +8,17 @@
 import io.vena.bosk.drivers.mongo.status.MongoStatus;
 import java.io.IOException;
 
+/**
+ * A {@link BoskDriver} that maintains the bosk state in a MongoDB database.
+ * Multiple bosks, potentially in multiple separate processes,
+ * can be configured to use the same database, thereby creating a replica set
+ * with all bosks sharing the same state and receiving updates from each other.
+ * <p>
+ *
+ * For convenience, if the database does not exist at the time of initialization,
+ * this driver will create it and populate it with the state returned by calling
+ * {@link BoskDriver#initialRoot} on the downstream driver.
+ */
 public sealed interface MongoDriver<R extends StateTreeNode>
 	extends BoskDriver<R>
 	permits MainDriver, FormatDriver {

bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UninitializedCollectionException.java

@@ -1,5 +1,15 @@
 package io.vena.bosk.drivers.mongo;
 
+/**
+ * Indicates that the database has been found to be in a state that
+ * could be considered "uninitialized", in the sense that we are permitted
+ * to respond by automatically initializing the database.
+ * <p>
+ * This is not the same as discovering that the database is simply in some unexpected state,
+ * in which case other exceptions may be thrown and the driver would likely disconnect
+ * rather than overwrite the database contents.
+ * Rather, we must have a fairly high degree of certainty that we're ok to start fresh.
+ */
 class UninitializedCollectionException extends Exception {
 	public UninitializedCollectionException() {
 	}

bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnprocessableEventException.java

@@ -3,7 +3,7 @@
 import com.mongodb.client.model.changestream.OperationType;
 
 /**
- * Indicate that no {@link FormatDriver} could cope with a particular
+ * Indicates that no {@link FormatDriver} could cope with a particular
  * change stream event. The framework responds with a (potentially expensive)
  * reload operation that avoids attempting to re-process that event;
  * in other words, using resume tokens would never be appropriate for these.

bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnrecognizedFormatException.java

@@ -1,5 +1,9 @@
 package io.vena.bosk.drivers.mongo;
 
+/**
+ * Indicates that we are unable to interpret the contents of
+ * the manifest document found in the database.
+ */
 class UnrecognizedFormatException extends Exception {
 	public UnrecognizedFormatException(String message) {
 		super(message);