@@ -10,118 +10,138 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Abstraction for JSON serialization/deserialization to decouple the SDK from any
- * specific JSON library.
+ * Reads and writes the JSON of ACP messages for the SDK, so that acp-core itself depends on no JSON
+ * library. The transports use it to write each message they send, to read each message that
+ * arrives, and to convert a message's params or result into the
+ * {@link com.agentclientprotocol.sdk.spec.AcpSchema} record the method expects. Most applications
+ * never call it: a transport created without a mapper gets one from {@link #createDefault()}.
  *
- * <p>
- * {@code acp-core} contains no implementation. One comes from a JSON module on the
- * classpath: {@code acp-json-jackson2} (Jackson 2, which the transport and agent-support
- * modules bring in) or {@code acp-json-jackson3} (Jackson 3). Each registers an
- * {@link AcpJsonMapperSupplier} discovered via {@link ServiceLoader}.
- * </p>
+ * <p>The implementation comes from a JSON module on the classpath: {@code acp-json-jackson2}
+ * ({@code JacksonAcpJsonMapper}, Jackson 2) or {@code acp-json-jackson3}
+ * ({@code Jackson3AcpJsonMapper}, Jackson 3). {@code acp-agent-support},
+ * {@code acp-streamable-http-jetty} and {@code acp-test} bring in {@code acp-json-jackson2}; with
+ * acp-core alone, add one of the two. Each module registers an {@link AcpJsonMapperSupplier}, and
+ * {@link #createDefault()} picks one. To configure Jackson yourself, create the module's mapper
+ * around your own Jackson mapper and pass it to the transport's constructor.
  *
- * <p>
- * Alternative implementations (e.g., for Micronaut serialization) can be provided by
- * implementing {@link AcpJsonMapperSupplier} and registering it in
- * {@code META-INF/services/com.agentclientprotocol.sdk.json.AcpJsonMapperSupplier}.
- * </p>
+ * <p>Implementations: the schema records carry Jackson annotations ({@code @JsonProperty},
+ * {@code @JsonInclude}, {@code @JsonTypeInfo}, {@code @JsonSubTypes}, {@code @JsonCreator},
+ * {@code @JsonValue}, {@code @JsonAnyGetter} and {@code @JsonAnySetter}), so a mapper must honour
+ * them to read and write ACP. A transport calls its mapper from several threads at once, so it must
+ * be safe for concurrent use. Reads and writes report failures as {@link IOException}; the SDK
+ * answers text that is not JSON with a parse error ({@code -32700}). A conversion whose value does
+ * not fit the target type must fail with {@link IllegalArgumentException}, which the SDK answers as
+ * invalid params ({@code -32602}). Register an implementation through an
+ * {@link AcpJsonMapperSupplier}.
  *
  * @author Mark Pollack
  */
 public interface AcpJsonMapper {
 
 	/**
-	 * Creates a default AcpJsonMapper from the {@link AcpJsonMapperSupplier}s found via
-	 * {@link ServiceLoader}. The choice is deterministic:
+	 * Returns a new mapper from the {@link AcpJsonMapperSupplier}s that {@link ServiceLoader} finds
+	 * with the current thread's context class loader. The choice does not depend on classpath
+	 * order:
 	 * <ol>
-	 * <li>if the system property {@code acp.json.mapper.supplier} is set, the supplier
-	 * with exactly that fully qualified class name is used (and it is an error if there is
-	 * none);</li>
-	 * <li>otherwise the supplier with the highest {@link AcpJsonMapperSupplier#priority()}
-	 * is used, ties broken by class name. With both SDK modules present,
-	 * {@code acp-json-jackson3} (priority -100) wins over {@code acp-json-jackson2}
-	 * (-200); an application supplier that keeps the default priority (0) wins over
-	 * both.</li>
+	 * <li>if the system property {@code acp.json.mapper.supplier} is set (and not blank), the
+	 * supplier whose class has exactly that fully qualified name is used;</li>
+	 * <li>otherwise the supplier with the highest {@link AcpJsonMapperSupplier#priority()} is used,
+	 * ties broken by class name. With both SDK modules present, {@code acp-json-jackson3} (priority
+	 * {@code -100}) wins over {@code acp-json-jackson2} ({@code -200}); an application supplier
+	 * that keeps the default priority ({@code 0}) wins over both.</li>
 	 * </ol>
-	 * @return a new AcpJsonMapper instance
-	 * @throws java.util.ServiceConfigurationError if no supplier is found, or none
-	 * matches the system property
+	 *
+	 * <p>Each call looks the suppliers up again and asks the chosen one for a mapper; the SDK's
+	 * suppliers build a new one every time, so keep the result rather than calling this per
+	 * message.
+	 * @return the chosen supplier's mapper
+	 * @throws java.util.ServiceConfigurationError if no supplier is found, or none has the class
+	 * named by the system property
+	 * @throws IllegalStateException if the chosen SDK module finds a Jackson older than it supports
+	 * (2.18.1 for Jackson 2, 3.0.0 for Jackson 3)
 	 */
 	static AcpJsonMapper createDefault() {
 		return AcpJsonMapperSelector.select().get();
 	}
 
 	/**
-	 * Deserialize JSON string into a target type.
-	 * @param content JSON as String
-	 * @param type target class
-	 * @return deserialized instance, or {@code null} when the JSON is the {@code null} literal
-	 * @param <T> generic type
-	 * @throws IOException on parse errors
+	 * Reads a JSON text as the given type.
+	 * @param content the JSON text
+	 * @param type the type to read
+	 * @param <T> the type to read
+	 * @return the value, or {@code null} when the text is the JSON literal {@code null}
+	 * @throws IOException if the text is not JSON or does not fit the type
 	 */
 	<T> @Nullable T readValue(String content, Class<T> type) throws IOException;
 
 	/**
-	 * Deserialize JSON bytes into a target type.
-	 * @param content JSON as bytes
-	 * @param type target class
-	 * @return deserialized instance, or {@code null} when the JSON is the {@code null} literal
-	 * @param <T> generic type
-	 * @throws IOException on parse errors
+	 * Reads JSON bytes as the given type, like {@link #readValue(String, Class)}.
+	 * @param content the JSON bytes
+	 * @param type the type to read
+	 * @param <T> the type to read
+	 * @return the value, or {@code null} when the bytes are the JSON literal {@code null}
+	 * @throws IOException if the bytes are not JSON or do not fit the type
 	 */
 	<T> @Nullable T readValue(byte[] content, Class<T> type) throws IOException;
 
 	/**
-	 * Deserialize JSON string into a parameterized target type.
-	 * @param content JSON as String
-	 * @param type parameterized type reference
-	 * @return deserialized instance, or {@code null} when the JSON is the {@code null} literal
-	 * @param <T> generic type
-	 * @throws IOException on parse errors
+	 * Reads a JSON text as a generic type, such as {@code List<AcpSchema.ContentBlock>}, that a
+	 * {@link TypeRef} captures.
+	 * @param content the JSON text
+	 * @param type the type to read
+	 * @param <T> the type to read
+	 * @return the value, or {@code null} when the text is the JSON literal {@code null}
+	 * @throws IOException if the text is not JSON or does not fit the type
 	 */
 	<T> @Nullable T readValue(String content, TypeRef<T> type) throws IOException;
 
 	/**
-	 * Deserialize JSON bytes into a parameterized target type.
-	 * @param content JSON as bytes
-	 * @param type parameterized type reference
-	 * @return deserialized instance, or {@code null} when the JSON is the {@code null} literal
-	 * @param <T> generic type
-	 * @throws IOException on parse errors
+	 * Reads JSON bytes as a generic type that a {@link TypeRef} captures, like
+	 * {@link #readValue(String, TypeRef)}.
+	 * @param content the JSON bytes
+	 * @param type the type to read
+	 * @param <T> the type to read
+	 * @return the value, or {@code null} when the bytes are the JSON literal {@code null}
+	 * @throws IOException if the bytes are not JSON or do not fit the type
 	 */
 	<T> @Nullable T readValue(byte[] content, TypeRef<T> type) throws IOException;
 
 	/**
-	 * Convert a value to a given type, useful for mapping nested JSON structures.
-	 * @param fromValue source value
-	 * @param type target class
-	 * @return converted value
-	 * @param <T> generic type
+	 * Converts a value to the given type as if it were written as JSON and read back. The
+	 * transports use it to turn the params or result of a message, read as maps and lists, into the
+	 * record the method expects.
+	 * @param fromValue the value, usually maps and lists read from JSON
+	 * @param type the type to convert to
+	 * @param <T> the type to convert to
+	 * @return the converted value
+	 * @throws IllegalArgumentException if the value does not fit the type
 	 */
 	<T> T convertValue(Object fromValue, Class<T> type);
 
 	/**
-	 * Convert a value to a given parameterized type.
-	 * @param fromValue source value
-	 * @param type target type reference
-	 * @return converted value
-	 * @param <T> generic type
+	 * Converts a value to a generic type that a {@link TypeRef} captures, like
+	 * {@link #convertValue(Object, Class)}.
+	 * @param fromValue the value, usually maps and lists read from JSON
+	 * @param type the type to convert to
+	 * @param <T> the type to convert to
+	 * @return the converted value
+	 * @throws IllegalArgumentException if the value does not fit the type
 	 */
 	<T> T convertValue(Object fromValue, TypeRef<T> type);
 
 	/**
-	 * Serialize an object to JSON string.
-	 * @param value object to serialize
-	 * @return JSON as String
-	 * @throws IOException on serialization errors
+	 * Writes a value, such as a JSON-RPC message, as JSON text.
+	 * @param value the value to write
+	 * @return the JSON text
+	 * @throws IOException if the value cannot be written as JSON
 	 */
 	String writeValueAsString(Object value) throws IOException;
 
 	/**
-	 * Serialize an object to JSON bytes.
-	 * @param value object to serialize
-	 * @return JSON as bytes
-	 * @throws IOException on serialization errors
+	 * Writes a value as JSON bytes in UTF-8.
+	 * @param value the value to write
+	 * @return the JSON bytes
+	 * @throws IOException if the value cannot be written as JSON
 	 */
 	byte[] writeValueAsBytes(Object value) throws IOException;
 
 
@@ -7,37 +7,40 @@
 import java.util.function.Supplier;
 
 /**
- * Strategy interface for providing an {@link AcpJsonMapper} implementation.
+ * Supplies the {@link AcpJsonMapper} that {@link AcpJsonMapper#createDefault()} returns. Each JSON
+ * module registers one with {@link java.util.ServiceLoader}, and {@code createDefault()} picks one
+ * by {@link #priority()}. Implement it to plug in a JSON library the SDK does not ship, or a
+ * Jackson mapper configured your way for every transport that creates its own mapper.
  *
- * <p>
- * Implementations are discovered at runtime via {@link java.util.ServiceLoader}.
- * To register an implementation, create a file at
- * {@code META-INF/services/com.agentclientprotocol.sdk.json.AcpJsonMapperSupplier}
- * containing the fully qualified class name of the supplier.
- * </p>
+ * <p>To register an implementation, list its fully qualified class name in
+ * {@code META-INF/services/com.agentclientprotocol.sdk.json.AcpJsonMapperSupplier}; ServiceLoader
+ * needs a public class with a public no-argument constructor. With the default priority it wins
+ * over the SDK's own suppliers. The system property {@code acp.json.mapper.supplier} chooses a
+ * supplier by class name instead (see {@link AcpJsonMapper#createDefault()}).
  *
- * <p>
- * When several suppliers are on the classpath, {@link AcpJsonMapper#createDefault()}
- * picks the one with the highest {@link #priority()}; see there for the full rule.
- * </p>
+ * <p>Implementations: {@link #get()} is called on every {@code createDefault()} call, and the
+ * mapper it returns must meet the {@link AcpJsonMapper} requirements, including use from several
+ * threads at once. {@link #priority()} returns {@link #DEFAULT_PRIORITY} unless overridden.
  *
  * @author Mark Pollack
  * @see AcpJsonMapper#createDefault()
  */
 public interface AcpJsonMapperSupplier extends Supplier<AcpJsonMapper> {
 
 	/**
-	 * The priority of a supplier that does not override {@link #priority()}. It is higher
-	 * than the priority of both SDK-provided suppliers, so an application's own supplier
-	 * wins over them without further configuration.
+	 * The priority of a supplier that does not override {@link #priority()}: {@value}. It is higher
+	 * than the priority of both SDK suppliers, so an application's own supplier wins over them
+	 * without further configuration.
 	 */
 	int DEFAULT_PRIORITY = 0;
 
 	/**
-	 * This supplier's priority when more than one supplier is on the classpath: the
-	 * highest value wins. The SDK's own suppliers use negative values ({@code
-	 * acp-json-jackson2} is {@code -200}, {@code acp-json-jackson3} is {@code -100}).
-	 * @return the priority, {@link #DEFAULT_PRIORITY} unless overridden
+	 * Returns this supplier's rank when {@link AcpJsonMapper#createDefault()} finds more than one:
+	 * the highest wins, ties broken by class name. The SDK's suppliers use negative values,
+	 * {@code -200} for {@code acp-json-jackson2} and {@code -100} for {@code acp-json-jackson3}.
+	 * The system property {@code acp.json.mapper.supplier}, when set, decides instead.
+	 * @implSpec Returns {@link #DEFAULT_PRIORITY}.
+	 * @return the priority
 	 */
 	default int priority() {
 		return DEFAULT_PRIORITY;
 
@@ -23,11 +23,20 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * Jackson 2 implementation of {@link AcpJsonMapper}, shipped in {@code acp-json-jackson2}.
- * Wraps a Jackson {@link ObjectMapper} but keeps the SDK decoupled from Jackson at the API
- * level. It keeps the package it had when it lived in {@code acp-core}, so code that
- * constructs it compiles unchanged. It needs Jackson 2.18.1 or later (jackson-core and
- * jackson-databind), which it checks when it is created.
+ * The Jackson 2 {@link AcpJsonMapper}, from the {@code acp-json-jackson2} module: it reads and
+ * writes ACP messages with a Jackson {@link ObjectMapper}. {@link AcpJsonMapper#createDefault()}
+ * returns one built on {@link #defaultObjectMapper()} when this is the only JSON module on the
+ * classpath; create one yourself to give a transport an {@code ObjectMapper} you configured. Use
+ * {@code acp-json-jackson3} instead when the application already runs on Jackson 3.
+ *
+ * <p>It needs jackson-core and jackson-databind 2.18.1 or later, and checks both when it is
+ * created: an older Jackson 2 fails then with an {@link IllegalStateException} that names the
+ * versions found, not later while reading a message. It lives in the package of
+ * {@link AcpJsonMapper}, which acp-core and this module share.
+ *
+ * <p>Reads and writes fail with Jackson's {@link IOException} subclasses, and conversions with
+ * {@link IllegalArgumentException}, as {@link AcpJsonMapper} requires. It is safe for concurrent
+ * use as long as the {@code ObjectMapper} is not reconfigured once in use.
  *
  * @author Mark Pollack
  */
@@ -38,27 +47,26 @@ public final class JacksonAcpJsonMapper implements AcpJsonMapper {
 	private final ObjectMapper objectMapper;
 
 	/**
-	 * The {@link ObjectMapper} the SDK uses by default: <em>lenient</em> about unknown
-	 * properties, because the ACP specification adds fields between releases and an agent
-	 * newer than this SDK must keep working. Each unknown property is logged once per
-	 * occurrence at DEBUG under this class's logger, so spec drift is observable without
-	 * making the wire strict.
+	 * Returns a new {@link ObjectMapper} set up the way the SDK reads and writes ACP; the module's
+	 * supplier builds its mapper on it. It differs from a bare {@code new ObjectMapper()} in two
+	 * ways:
+	 * <ul>
+	 * <li>unknown properties are skipped, not rejected, because the ACP specification adds fields
+	 * between releases and an agent newer than this SDK must keep working. Each skipped property is
+	 * logged at DEBUG under this class's logger, so drift can be seen without making the wire
+	 * strict;</li>
+	 * <li>a scalar of the wrong JSON type is refused rather than coerced (a number or boolean where
+	 * a string is expected, a string where a number or boolean is expected): the SDK answers such
+	 * params {@code -32602} (Invalid params), and a coerced value would hide a peer's bug.</li>
+	 * </ul>
 	 *
-	 * <p>
-	 * Strictness is the mapper's decision, not the schema's: the schema records carry no
+	 * <p>Strictness is the mapper's choice, not the schema's: the schema records carry no
 	 * {@code @JsonIgnoreProperties}, so a mapper with
-	 * {@link DeserializationFeature#FAIL_ON_UNKNOWN_PROPERTIES} enabled (Jackson's own
-	 * default for a bare {@code new ObjectMapper()}) fails on the first unknown field.
-	 * Consumers who want their own configuration on top of the SDK's defaults should start
-	 * from this method's result.
-	 * </p>
-	 * <p>
-	 * A scalar of the wrong JSON type is refused rather than coerced (a number or boolean for
-	 * a string, a string for a number or boolean): JSON-RPC answers such params -32602 Invalid
-	 * params, and a coerced value would hide a peer's bug.
-	 * </p>
-	 *
-	 * @return a new, independently configurable lenient mapper
+	 * {@link DeserializationFeature#FAIL_ON_UNKNOWN_PROPERTIES} enabled (a bare
+	 * {@code ObjectMapper}'s default) fails on the first unknown field. To customise the SDK's
+	 * settings, start from this method's result and pass it to
+	 * {@link #JacksonAcpJsonMapper(ObjectMapper)}.
+	 * @return a new mapper, shared with no other caller
 	 */
 	public static ObjectMapper defaultObjectMapper() {
 		return JsonMapper.builder()
@@ -91,11 +99,13 @@ public boolean handleUnknownProperty(DeserializationContext ctxt, JsonParser p,
 	}
 
 	/**
-	 * Constructs a new JacksonAcpJsonMapper with the given ObjectMapper.
-	 * @param objectMapper the ObjectMapper to use. Must not be null.
-	 * @throws IllegalArgumentException if the provided ObjectMapper is null.
-	 * @throws IllegalStateException if the Jackson 2 on the classpath is older than the supported
-	 * floor (see the type comment)
+	 * Creates a mapper that reads and writes with the given {@code ObjectMapper}, used as is: none
+	 * of the settings of {@link #defaultObjectMapper()} are added.
+	 * @param objectMapper the Jackson mapper; start from {@link #defaultObjectMapper()} to keep the
+	 * SDK's settings
+	 * @throws IllegalArgumentException if {@code objectMapper} is null
+	 * @throws IllegalStateException if the jackson-core or jackson-databind on the classpath is
+	 * older than 2.18.1
 	 */
 	public JacksonAcpJsonMapper(ObjectMapper objectMapper) {
 		JacksonVersions.requireSupported();
@@ -106,8 +116,9 @@ public JacksonAcpJsonMapper(ObjectMapper objectMapper) {
 	}
 
 	/**
-	 * Returns the underlying Jackson {@link ObjectMapper}.
-	 * @return the ObjectMapper instance
+	 * Returns the {@code ObjectMapper} this mapper reads and writes with: the one given to the
+	 * constructor, not a copy.
+	 * @return the Jackson mapper
 	 */
 	public ObjectMapper getObjectMapper() {
 		return objectMapper;