Proofread comments and documentation

.agents/memory/reference/cache-warm-window.md

@@ -18,7 +18,7 @@ same cache slot — provided they fall within the TTL.
 Developers must have `ENABLE_PROMPT_CACHING_1H=1` set, otherwise the
 window is too short for cross-session hits to occur reliably.
 This setting will work ONLY for Claude Code which runs the CLI binary.
-It will not work for JetBrains Air or any other IDE plugin which does not
+It will not work for JetBrains Air or any other IDE plugin that does not
 run the Claude Code CLI binary.
 
 **Cache is per Anthropic workspace.** All developers authenticated via the

.agents/tasks/add-suppliers2-iterators2.md

@@ -23,7 +23,7 @@ can later drop its copies.
 - `io.spine.util` already hosts the Guava-companion naming pattern
   (`Preconditions2`, `Predicates2`) and is `@NullMarked` via `package-info.java`.
 - The classes keep `@Internal` (as in the source PR): they are framework
-  plumbing; widening to public API later is non-breaking, the reverse is not.
+  plumbing; widening to public API later is non-breaking; the reverse is not.
 - New tests follow `kotlin-jvm-tester` conventions: Kotlin, `Spec` suffix,
   `internal`, `UtilityClassTest` base (private ctor + final +
   `NullPointerTester` on public statics), Kotest assertions.

.agents/tasks/archive/raise-base-coverage.md

@@ -39,7 +39,7 @@ gaps closed without weakening Codecov settings.
 - [x] Analyze whether `io.spine.code.fs` is used in SpineEventEngine projects.
 - [x] Mark `io.spine.code.fs` types that are not used by any project as deprecated.
 - [x] Deprecate `io.spine.code.fs` types that are not used.
-- [x] Analyse whether `RejectionType` is used in Spine SDK projects and deprecate if not.
+- [x] Analyze whether `RejectionType` is used in Spine SDK projects and deprecate if not.
 - [x] Finalize test cases for the remaining non-deprecated API and wait for
   approval to write tests.
 - [x] Add approved Kotlin `*Spec` tests using stubs, not mocks.

annotations/src/main/kotlin/io/spine/annotation/GeneratedMixin.kt

@@ -37,14 +37,14 @@ import kotlin.annotation.AnnotationTarget.CLASS
  * ## Motivation
  *
  * This annotation allows documenting the intent of the interface.
- * It also allows to instruct IDEs to consider annotated interfaces as implemented before
+ * It also allows instructing IDEs to consider annotated interfaces as implemented before
  * the code generation phase, or if the interfaces are used only from projects that depend
  * on the one declaring these interfaces.
  *
- * For example, Spine Base project introduces the `io.spine.base.CommandMessage` interface.
+ * For example, the Spine Base project introduces the `io.spine.base.CommandMessage` interface.
  * There are no command messages generated in the Base project because it does not provide any
  * backend API. The interface is used by multiple subprojects of the Spine SDK that depend
- * on Base, but it is not used withing the project.
+ * on Base, but it is not used within the project.
  * Annotating the interface with `GeneratedMixin` addresses the issue.
  *
  * ## Creating a mixin interface

base/build.gradle.kts

@@ -117,7 +117,7 @@ protobuf {
 }
 
 /**
- * Remove the code generated for Google Protobuf library types.
+ * Removes the code generated for Google Protobuf library types.
  *
  * The code for the `com.google` package was generated because we wanted
  * to have descriptors for all the types, including those from Google Protobuf library.
@@ -150,7 +150,7 @@ private val Project.generatedDir
 /**
  * Obtains the `generated` directory for the source set of the task.
  *
- * If [language] is specified returns the subdirectory for this language.
+ * If [language] is specified, returns the subdirectory for this language.
  */
 private fun GenerateProtoTask.generatedDir(language: String = ""): File {
     val path = "${project.generatedDir}/${sourceSet.name}/$language"

base/src/main/java/io/spine/base/Errors.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2022, TeamDev. All rights reserved.
+ * Copyright 2026, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following
@@ -43,7 +43,7 @@ private Errors() {
     }
 
     /**
-     * Creates new instance of {@link Error} by the passed {@code Throwable}.
+     * Creates a new instance of {@link Error} by the passed {@code Throwable}.
      */
     public static Error fromThrowable(Throwable throwable) {
         var result = toErrorBuilder(throwable);

base/src/main/java/io/spine/base/Field.java

@@ -402,7 +402,7 @@ static FieldPath doParse(String fieldPath) {
     }
 
     /**
-     * If the passed value is {@code EnumValueDescriptor} converts it to the corresponding
+     * If the passed value is {@code EnumValueDescriptor}, converts it to the corresponding
      * Java enum value. Otherwise, returns the passed value.
      *
      * <p>{@link Message#getField(FieldDescriptor)} returns {@code EnumValueDescriptor} if
@@ -448,7 +448,7 @@ private static Object convertIfEnum(Object currentValue) {
         return field;
     }
 
-    /** Ensures that the passed filed name does not contain the path separator. */
+    /** Ensures that the passed field name does not contain the path separator. */
     private static void checkName(String fieldName) {
         checkNotEmptyOrBlank(fieldName);
         checkArgument(

base/src/main/java/io/spine/base/IdType.java

@@ -284,7 +284,7 @@ static <I> IdType of(I id) {
     }
 
     /**
-     * Returns {@code true} if the passed instances of {@link Object} matches this
+     * Returns {@code true} if the passed instance of {@link Object} matches this
      * type of identifiers; {@code false} otherwise.
      */
     abstract <I> boolean matchValue(I id);

base/src/main/java/io/spine/base/Identifier.java

@@ -289,7 +289,7 @@ private static <I> IllegalArgumentException unsupportedClass(Class<I> idClass) {
         until Java 18. So we link to the class Javadoc where the header comes first. */
     public static <I> void checkSupported(Class<I> idClass) {
         checkNotNull(idClass);
-        // Even through `getType()` can never return null, we use its return value here
+        // Even though `getType()` can never return null, we use its return value here
         // instead of annotating the method so that the returned value can be ignored
         // just because of this one usage.
         var type = toType(idClass);
@@ -343,7 +343,7 @@ public static boolean isSupportedIdType(FieldDescriptor field) {
      * Wraps the passed ID value into an instance of {@link Any}.
      *
      * <p>The passed value must be of one of the supported types listed below.
-     * The type of the value wrapped in to the returned instance is defined by the type
+     * The type of the value wrapped into the returned instance is defined by the type
      * of the passed value:
      * <ul>
      *   <li>For classes implementing {@link Message} — the value of the message itself
@@ -371,7 +371,7 @@ public static <I> Any pack(I id) {
     /**
      * Extracts an ID value from the passed {@code Any} instance.
      *
-     * <p>Returned type depends on the type of the message wrapped into {@code Any}:
+     * <p>The returned type depends on the type of the message wrapped into {@code Any}:
      * <ul>
      *   <li>{@code String} for unwrapped {@link StringValue}
      *   <li>{@code Integer} for unwrapped {@link Int32Value}

base/src/main/java/io/spine/base/RejectionThrowable.java

@@ -101,7 +101,7 @@ public synchronized RejectionThrowable initProducer(Any producerId) {
     }
 
     /**
-     * Obtains ID of the entity that has thrown the message.
+     * Obtains the ID of the entity that has thrown the message.
      */
     public synchronized Optional<Any> producerId() {
         return Optional.ofNullable(producerId);

base/src/main/java/io/spine/base/Time.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2022, TeamDev. All rights reserved.
+ * Copyright 2026, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following
@@ -89,7 +89,7 @@ public static synchronized ZoneId currentTimeZone() {
     }
 
     /**
-     * Sets provider of the current time.
+     * Sets the provider of the current time.
      *
      * <p>The most common scenario for using this method is test cases of code that deals
      * with current time.
@@ -184,7 +184,7 @@ public Timestamp currentTime() {
     /**
      * Provides an incremental value of nanoseconds for the local JVM.
      *
-     * <p>In most cases, the JVM and underlying OS provides the millisecond-level precision at best.
+     * <p>In most cases, the JVM and underlying OS provide the millisecond-level precision at best.
      * Therefore, the messages produced in such a virtual machine are often stamped
      * with the same time value. However, most of the message-ordering routines require
      * the distinct time values for proper work.
@@ -201,7 +201,7 @@ public Timestamp currentTime() {
      * It is designed to keep the millisecond value provided by a typical-JVM system clock intact.
      *
      * <p>The nanosecond value is reset for each new passed {@code seconds} and {@code nanos}
-     * values. That allows to receive {@code 1 000} distinct time values per millisecond.
+     * values. That allows receiving {@code 1 000} distinct time values per millisecond.
      *
      * <p>In case the upper bound of the nanos is reached, meaning that there were more than
      * {@code 1 000} calls to this class within a millisecond, the nanosecond value is reset

base/src/main/java/io/spine/code/java/ClassName.java

@@ -96,7 +96,7 @@ public static ClassName of(@FullyQualifiedName String className) {
     }
 
     /**
-     * Creates a class name from the specified package the and simple name.
+     * Creates a class name from the specified package and simple name.
      *
      * @param packageName
      *         the name of the class package
@@ -240,7 +240,7 @@ public String canonicalName() {
      * The actual returned value is obtained from {@link Class#getName()}. In most cases,
      * the {@code Class.getName()} and the JDK-spec binary name coincide.
      *
-     * @return the name with the {@link #OUTER_CLASS_DELIMITER}s between nested classed if any
+     * @return the name with the {@link #OUTER_CLASS_DELIMITER}s between nested classes if any
      * @implSpec This method returns the same value as does the {@code value()} method. Use
      *         this method for more clarity in the client code.
      */
@@ -306,7 +306,7 @@ public String withoutPackage() {
     }
 
     /**
-     * Obtain the part of the name after the last {@link #DOT_SEPARATOR .} (dot) symbol.
+     * Obtains the part of the name after the last {@link #DOT_SEPARATOR .} (dot) symbol.
      *
      * @param fullName
      *         a full class name
@@ -334,10 +334,10 @@ private int packageEndIndex() {
     }
 
     /**
-     * Obtains the simple name of the top level class.
+     * Obtains the simple name of the top-level class.
      *
      * <p>If this class is top level, returns the simple name of this class.
-     * If this class is nested, returns the name of the declaring top level class.
+     * If this class is nested, returns the name of the declaring top-level class.
      */
     public SimpleClassName topLevelClass() {
         var qualifiedClassName = afterDot(value());

base/src/main/java/io/spine/code/java/PackageName.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2022, TeamDev. All rights reserved.
+ * Copyright 2026, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following
@@ -50,7 +50,7 @@ private PackageName(String value) {
     }
 
     /**
-     * Creates instance for the passed package name.
+     * Creates an instance for the passed package name.
      *
      * @param value
      *         the package name, which cannot be empty or blank

base/src/main/java/io/spine/code/proto/ColumnOption.java

@@ -69,8 +69,8 @@ public static boolean hasColumns(MessageType messageType) {
     /**
      * Returns all fields of a message type that are declared as columns.
      *
-     * <p>If the message type is not eligible for having columns, returns empty list regardless of
-     * how fields are declared.
+     * <p>If the message type is not eligible for having columns, returns an empty list regardless
+     * of how fields are declared.
      */
     public static ImmutableList<FieldDeclaration> columnsOf(MessageType messageType) {
         if (!declaresEntity(messageType)) {

base/src/main/java/io/spine/code/proto/EntityStateOption.java

@@ -37,7 +37,7 @@
  * An option for a message representing a state of the entity that defines its kind and visibility
  * to queries.
  *
- * <p>There are four kids of options, namely, Aggregate, Projection, Process Manager, and Entity.
+ * <p>There are four kinds of options, namely, Aggregate, Projection, Process Manager, and Entity.
  */
 @Immutable
 public final class EntityStateOption extends MessageOption<EntityOption> {

base/src/main/java/io/spine/code/proto/FieldDeclaration.java

@@ -100,7 +100,7 @@ public int number() {
     }
 
     /**
-     * Obtains descriptor of the field.
+     * Obtains the descriptor of the field.
      */
     public FieldDescriptor descriptor() {
         return field;
@@ -140,7 +140,7 @@ private boolean sameMessageType(Message msg) {
     }
 
     /**
-     * Obtains fully-qualified canonical name of the Java class that corresponds to the declared
+     * Obtains the fully-qualified canonical name of the Java class that corresponds to the declared
      * type of the field.
      *
      * <p>If the field is {@code repeated}, obtains the name of the elements.
@@ -271,7 +271,7 @@ public boolean isCollection() {
     }
 
     /**
-     * Determines whether the field marked as {@code repeated}.
+     * Determines whether the field is marked as {@code repeated}.
      *
      * <p>A map field is not considered repeated.
      *
@@ -311,7 +311,7 @@ public MessageType messageType() {
     }
 
     /**
-     * Obtains a class name of the field type or a name a wrapper class, if the field is scalar.
+     * Obtains a class name of the field type or a name of a wrapper class, if the field is scalar.
      */
     @Internal
     public ClassName className() {

base/src/main/java/io/spine/code/proto/FieldName.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2022, TeamDev. All rights reserved.
+ * Copyright 2026, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
- * http://www.apache.org/licenses/LICENSE-2.0
+ * https://www.apache.org/licenses/LICENSE-2.0
  *
  * Redistribution and use in source and/or binary forms, with or without
  * modification, must retain the above copyright notice and the following
@@ -77,7 +77,7 @@ public static FieldName of(FieldDescriptorProto field) {
     }
 
     /**
-     * Obtains immutable list of words used in the name of the field.
+     * Obtains an immutable list of words used in the name of the field.
      *
      * <p>A word is a part of the name, the first letter of which should be capitalized
      * when converting {@linkplain #toCamelCase() to CamelCase}.

base/src/main/java/io/spine/code/proto/FileSet.java

@@ -245,14 +245,14 @@ public FileSet filter(Predicate<FileDescriptor> predicate) {
     }
 
     /**
-     * Obtains immutable view of the files in this set.
+     * Obtains an immutable view of the files in this set.
      */
     public ImmutableSet<FileDescriptor> files() {
         return ImmutableSet.copyOf(files.values());
     }
 
     /**
-     * Obtains array with the files of this set.
+     * Obtains an array with the files of this set.
      */
     FileDescriptor[] toArray() {
         return files.values()
@@ -279,7 +279,7 @@ public boolean containsAll(Collection<FileName> fileNames) {
     }
 
     /**
-     * Obtains the set of the files that match passed names.
+     * Obtains the set of the files that match the passed names.
      */
     public FileSet find(Collection<FileName> fileNames) {
         Map<FileName, FileDescriptor> found = newHashMapWithExpectedSize(fileNames.size());
@@ -302,7 +302,7 @@ public Optional<FileDescriptor> tryFind(FileName fileName) {
     }
 
     /**
-     * Adds file to the set.
+     * Adds a file to the set.
      */
     @CanIgnoreReturnValue
     public boolean add(FileDescriptor file) {
@@ -329,7 +329,7 @@ public boolean isEmpty() {
     }
 
     /**
-     * Returns a string with alphabetically sorted list of files of this set.
+     * Returns a string with an alphabetically sorted list of files of this set.
      */
     @Override
     public String toString() {

base/src/main/java/io/spine/code/proto/LocationPath.java

@@ -68,7 +68,7 @@ private LocationPath(Iterable<Integer> items, boolean check) {
         this.path = ImmutableList.copyOf(check ? checkPath(items) : items);
     }
 
-    /** Creates an copy of the passed path. */
+    /** Creates a copy of the passed path. */
     LocationPath(LocationPath start) {
         this(start.path, false);
     }

base/src/main/java/io/spine/code/proto/PackageName.java

@@ -79,7 +79,7 @@ public static PackageName googleProtobuf() {
     }
 
     /**
-     * Obtains Protobuf package delimiter.
+     * Obtains the Protobuf package delimiter.
      */
     public static String delimiter() {
         return DELIMITER;