phase 1: envelope, IDs, errors, extensions, event log (gate 1)

Author: nficano

PLAN.md

@@ -46,13 +46,18 @@ tasks.withType<JavaCompile>().configureEach {
             "-Werror",
             "-Xlint:all",
             "-Xlint:-processing",
+            // ulid-creator is an automatic module (no module descriptor).
+            "-Xlint:-requires-automatic",
             "-parameters",
         ),
     )
     options.errorprone {
         disableWarningsInGeneratedCode.set(true)
         option("NullAway:AnnotatedPackages", "dev.arcp")
         error("NullAway")
+        // `@return ...` is an idiomatic Javadoc summary; the Google style
+        // checker disagrees but we accept it.
+        disable("MissingSummary")
     }
 }
 
@@ -89,7 +94,8 @@ spotless {
 }
 
 jacoco {
-    toolVersion = "0.8.12"
+    // JaCoCo 0.8.13+ adds support for Java 25 class major version 69.
+    toolVersion = "0.8.13"
 }
 
 tasks.named<JacocoReport>("jacocoTestReport") {

lib/build.gradle.kts

@@ -0,0 +1,26 @@
+package dev.arcp.envelope;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.databind.module.SimpleModule;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+
+/**
+ * Factory for a Jackson {@link ObjectMapper} configured for ARCP wire format
+ * (RFC §6.1): JSR-310 {@code Instant} support, ISO-8601 timestamps, and a
+ * custom {@link Envelope} deserializer that resolves the envelope-level
+ * {@code type} discriminator via {@link MessageType#register(String, Class)}.
+ */
+public final class ARCPMapper {
+
+	private ARCPMapper() {
+	}
+
+	/** @return a fresh, fully-configured mapper. Callers MAY cache it. */
+	public static ObjectMapper create() {
+		SimpleModule envelopes = new SimpleModule("arcp-envelopes");
+		envelopes.addDeserializer(Envelope.class, new EnvelopeDeserializer());
+		return new ObjectMapper().registerModule(new JavaTimeModule()).registerModule(envelopes)
+				.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+	}
+}

lib/src/main/java/dev/arcp/envelope/ARCPMapper.java

@@ -0,0 +1,82 @@
+package dev.arcp.envelope;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import dev.arcp.ids.IdempotencyKey;
+import dev.arcp.ids.JobId;
+import dev.arcp.ids.MessageId;
+import dev.arcp.ids.SessionId;
+import dev.arcp.ids.SpanId;
+import dev.arcp.ids.StreamId;
+import dev.arcp.ids.SubscriptionId;
+import dev.arcp.ids.TraceId;
+import java.time.Instant;
+import java.util.Map;
+import java.util.Objects;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * ARCP wire envelope (RFC §6.1).
+ *
+ * <p>
+ * Required: {@link #arcp}, {@link #id}, {@link #type}, {@link #timestamp},
+ * {@link #payload}. Conditional: {@link #sessionId}, {@link #jobId},
+ * {@link #streamId}, {@link #subscriptionId}. Recommended: {@link #traceId},
+ * {@link #spanId}, {@link #parentSpanId}. Optional: {@link #correlationId},
+ * {@link #causationId}, {@link #idempotencyKey}, {@link #priority},
+ * {@link #extensions}, {@link #source}, {@link #target}.
+ *
+ * <p>
+ * The {@link #type} field is the envelope-level discriminator (RFC §6.1.1). The
+ * compact constructor enforces {@code type.equals(payload.type())}.
+ * Deserialization is performed by {@link EnvelopeDeserializer}, registered via
+ * {@link ARCPMapper#create()}.
+ */
+@JsonDeserialize(using = EnvelopeDeserializer.class)
+@JsonPropertyOrder({"arcp", "id", "type", "timestamp", "session_id", "job_id", "stream_id", "subscription_id",
+		"trace_id", "span_id", "parent_span_id", "correlation_id", "causation_id", "idempotency_key", "priority",
+		"source", "target", "extensions", "payload"})
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record Envelope(@JsonProperty("arcp") String arcp, @JsonProperty("id") MessageId id,
+		@JsonProperty("type") String type, @JsonProperty("timestamp") Instant timestamp,
+		@JsonProperty("session_id") @Nullable SessionId sessionId, @JsonProperty("job_id") @Nullable JobId jobId,
+		@JsonProperty("stream_id") @Nullable StreamId streamId,
+		@JsonProperty("subscription_id") @Nullable SubscriptionId subscriptionId,
+		@JsonProperty("trace_id") @Nullable TraceId traceId, @JsonProperty("span_id") @Nullable SpanId spanId,
+		@JsonProperty("parent_span_id") @Nullable SpanId parentSpanId,
+		@JsonProperty("correlation_id") @Nullable MessageId correlationId,
+		@JsonProperty("causation_id") @Nullable MessageId causationId,
+		@JsonProperty("idempotency_key") @Nullable IdempotencyKey idempotencyKey,
+		@JsonProperty("priority") @Nullable Priority priority, @JsonProperty("source") @Nullable String source,
+		@JsonProperty("target") @Nullable String target,
+		@JsonProperty("extensions") @Nullable Map<String, JsonNode> extensions,
+		@JsonProperty("payload") MessageType payload) {
+
+	/** Wire-format protocol version this SDK speaks. */
+	public static final String PROTOCOL_VERSION = "1.0";
+
+	public Envelope {
+		Objects.requireNonNull(arcp, "arcp");
+		Objects.requireNonNull(id, "id");
+		Objects.requireNonNull(type, "type");
+		Objects.requireNonNull(timestamp, "timestamp");
+		Objects.requireNonNull(payload, "payload");
+		if (!type.equals(payload.type())) {
+			throw new IllegalArgumentException("envelope type=" + type + " mismatches payload type=" + payload.type());
+		}
+	}
+
+	/**
+	 * Build a minimally-valid envelope with current protocol version and the given
+	 * timestamp. The {@code type} discriminator is derived from
+	 * {@code payload.type()}.
+	 */
+	public static Envelope of(MessageId id, Instant timestamp, MessageType payload) {
+		Objects.requireNonNull(payload, "payload");
+		return new Envelope(PROTOCOL_VERSION, id, payload.type(), timestamp, null, null, null, null, null, null, null,
+				null, null, null, null, null, null, null, payload);
+	}
+}

lib/src/main/java/dev/arcp/envelope/Envelope.java

@@ -0,0 +1,118 @@
+package dev.arcp.envelope;
+
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import dev.arcp.ids.IdempotencyKey;
+import dev.arcp.ids.JobId;
+import dev.arcp.ids.MessageId;
+import dev.arcp.ids.SessionId;
+import dev.arcp.ids.SpanId;
+import dev.arcp.ids.StreamId;
+import dev.arcp.ids.SubscriptionId;
+import dev.arcp.ids.TraceId;
+import java.io.IOException;
+import java.time.Instant;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.Map;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Custom Jackson deserializer for {@link Envelope}. Resolves the envelope-level
+ * {@code type} discriminator (RFC §6.1.1) to a concrete {@link MessageType}
+ * variant via {@link MessageType#register(String, Class)}.
+ */
+final class EnvelopeDeserializer extends StdDeserializer<Envelope> {
+
+	private static final long serialVersionUID = 1L;
+
+	EnvelopeDeserializer() {
+		super(Envelope.class);
+	}
+
+	@Override
+	public Envelope deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
+		ObjectNode node = p.readValueAsTree();
+		String type = requireText(node, "type");
+		Class<? extends MessageType> payloadClass = MessageType.Registry.resolve(type);
+		JsonNode payloadNode = node.get("payload");
+		if (payloadNode == null) {
+			throw ctxt.weirdStringException(type, Envelope.class, "missing payload");
+		}
+		MessageType payload = ctxt.readTreeAsValue(payloadNode, payloadClass);
+
+		return new Envelope(requireText(node, "arcp"), readId(node, "id", MessageId.class, ctxt), type,
+				readInstant(node, "timestamp", ctxt), readNullable(node, "session_id", SessionId.class, ctxt),
+				readNullable(node, "job_id", JobId.class, ctxt), readNullable(node, "stream_id", StreamId.class, ctxt),
+				readNullable(node, "subscription_id", SubscriptionId.class, ctxt),
+				readNullable(node, "trace_id", TraceId.class, ctxt), readNullable(node, "span_id", SpanId.class, ctxt),
+				readNullable(node, "parent_span_id", SpanId.class, ctxt),
+				readNullable(node, "correlation_id", MessageId.class, ctxt),
+				readNullable(node, "causation_id", MessageId.class, ctxt),
+				readNullable(node, "idempotency_key", IdempotencyKey.class, ctxt),
+				readNullable(node, "priority", Priority.class, ctxt), readText(node, "source"),
+				readText(node, "target"), readExtensions(node), payload);
+	}
+
+	private static String requireText(ObjectNode node, String field) {
+		JsonNode v = node.get(field);
+		if (v == null || v.isNull()) {
+			throw new IllegalArgumentException("envelope missing required field " + field);
+		}
+		return v.asText();
+	}
+
+	private static <T> T readId(ObjectNode node, String field, Class<T> cls, DeserializationContext ctxt)
+			throws IOException {
+		JsonNode v = node.get(field);
+		if (v == null || v.isNull()) {
+			throw new IllegalArgumentException("envelope missing required field " + field);
+		}
+		return ctxt.readTreeAsValue(v, cls);
+	}
+
+	private static Instant readInstant(ObjectNode node, String field, DeserializationContext ctxt) throws IOException {
+		JsonNode v = node.get(field);
+		if (v == null || v.isNull()) {
+			throw new IllegalArgumentException("envelope missing required field " + field);
+		}
+		return ctxt.readTreeAsValue(v, Instant.class);
+	}
+
+	@Nullable
+	private static <T> T readNullable(ObjectNode node, String field, Class<T> cls, DeserializationContext ctxt)
+			throws IOException {
+		JsonNode v = node.get(field);
+		if (v == null || v.isNull()) {
+			return null;
+		}
+		return ctxt.readTreeAsValue(v, cls);
+	}
+
+	@Nullable
+	private static String readText(ObjectNode node, String field) {
+		JsonNode v = node.get(field);
+		return (v == null || v.isNull()) ? null : v.asText();
+	}
+
+	@Nullable
+	private static Map<String, JsonNode> readExtensions(ObjectNode node) {
+		JsonNode v = node.get("extensions");
+		if (v == null || v.isNull()) {
+			return null;
+		}
+		if (!v.isObject()) {
+			throw new IllegalArgumentException("extensions must be an object");
+		}
+		Map<String, JsonNode> out = new HashMap<>();
+		Iterator<Map.Entry<String, JsonNode>> it = v.properties().iterator();
+		while (it.hasNext()) {
+			Map.Entry<String, JsonNode> e = it.next();
+			out.put(e.getKey(), e.getValue());
+		}
+		return out;
+	}
+}

lib/src/main/java/dev/arcp/envelope/EnvelopeDeserializer.java

@@ -0,0 +1,65 @@
+package dev.arcp.envelope;
+
+import dev.arcp.messages.control.Ping;
+import dev.arcp.messages.control.Pong;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Sealed root of every ARCP payload variant (RFC §6.2).
+ *
+ * <p>
+ * Concrete variants register themselves with {@link #register(String, Class)};
+ * {@link Envelope} uses the registry during JSON deserialization to map the
+ * envelope-level {@code type} discriminator to the right record class.
+ * {@code switch} expressions over {@code MessageType} are compile-time
+ * exhaustive — the registry exists only for the wire-format mapping, not for
+ * dispatch.
+ */
+public sealed interface MessageType permits Ping, Pong {
+
+	/** @return the wire-format discriminator (e.g. {@code "ping"}). */
+	String type();
+
+	/** Mutable mapping from wire type string to the concrete record class. */
+	final class Registry {
+		private static final Map<String, Class<? extends MessageType>> MAP = new ConcurrentHashMap<>();
+
+		static {
+			MAP.put("ping", Ping.class);
+			MAP.put("pong", Pong.class);
+		}
+
+		private Registry() {
+		}
+
+		static Class<? extends MessageType> resolve(String type) {
+			Class<? extends MessageType> c = MAP.get(type);
+			if (c == null) {
+				throw new IllegalArgumentException("unknown message type: " + type);
+			}
+			return c;
+		}
+
+		static void put(String type, Class<? extends MessageType> cls) {
+			MAP.put(type, cls);
+		}
+
+		static boolean isKnown(String type) {
+			return MAP.containsKey(type);
+		}
+	}
+
+	/**
+	 * Register a wire-format type string for a concrete variant. Idempotent. Used
+	 * by additional message-type modules added in later phases.
+	 */
+	static void register(String type, Class<? extends MessageType> cls) {
+		Registry.put(type, cls);
+	}
+
+	/** @return {@code true} if {@code type} is a recognized variant. */
+	static boolean isKnown(String type) {
+		return Registry.isKnown(type);
+	}
+}

lib/src/main/java/dev/arcp/envelope/MessageType.java

@@ -0,0 +1,28 @@
+package dev.arcp.envelope;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Envelope priority (RFC §6.5). Ordering:
+ * {@code low < normal < high < critical}.
+ *
+ * <p>
+ * {@code critical} is reserved for permission requests blocking real human
+ * action and terminal job events. Runtimes SHOULD reorder between streams but
+ * MUST NEVER reorder within a {@code stream_id}.
+ */
+public enum Priority {
+	LOW, NORMAL, HIGH, CRITICAL;
+
+	/** @return canonical lowercase wire form. */
+	@JsonValue
+	public String wire() {
+		return name().toLowerCase(java.util.Locale.ROOT);
+	}
+
+	@JsonCreator
+	public static Priority fromWire(String s) {
+		return Priority.valueOf(s.toUpperCase(java.util.Locale.ROOT));
+	}
+}

lib/src/main/java/dev/arcp/envelope/Priority.java

@@ -0,0 +1,12 @@
+/**
+ * Wire-format envelope (RFC §6.1) and message-type discriminator.
+ *
+ * <p>
+ * {@link dev.arcp.envelope.Envelope} carries every §6.1 field;
+ * {@link dev.arcp.envelope.MessageType} is the sealed root of the payload
+ * hierarchy. Jackson polymorphism is configured directly on the sealed
+ * interface via {@code @JsonTypeInfo} + {@code @JsonSubTypes}, giving
+ * compile-time exhaustive {@code switch} dispatch.
+ */
+@org.jspecify.annotations.NullMarked
+package dev.arcp.envelope;