feat(runtime): surface INVALID_REQUEST on malformed envelopes (§12)

`WebSocketTransport.TryDeserialize` and the equivalent path in
`StdioTransport` previously swallowed `ArcpException`/`JsonException`
and returned null, so the misbehaving peer kept sending bad envelopes
with no feedback. Spec §12 explicitly defines `INVALID_REQUEST` as the
response.

Introduce an internal `arcp.invalid_envelope` sentinel envelope plus
the matching `InvalidEnvelopePayload` that transports yield on parse
failure. `SessionState.Dispatch` recognizes the sentinel and throws
`InvalidRequestException`, which the existing receiver-loop catch
converts into an outbound `session.error{INVALID_REQUEST}`. The
sentinel is never put on the wire.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nficano

src/Arcp.Core/Envelope/MessageTypeRegistry.cs

@@ -49,6 +49,7 @@ public static MessageTypeRegistry CreateCoreCatalog()
         r.Register(MessageTypeNames.SessionJobs, typeof(SessionJobsPayload));
         r.Register(MessageTypeNames.SessionError, typeof(SessionErrorPayload));
         r.Register(MessageTypeNames.SessionResume, typeof(SessionResumePayload));
+        r.Register(MessageTypeNames.InvalidEnvelope, typeof(InvalidEnvelopePayload));
         r.Register(MessageTypeNames.JobSubmit, typeof(JobSubmitPayload));
         r.Register(MessageTypeNames.JobAccepted, typeof(JobAcceptedPayload));
         r.Register(MessageTypeNames.JobEvent, typeof(JobEventPayload));

src/Arcp.Core/Messages/InvalidEnvelopePayload.cs

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+using System.Text.Json.Serialization;
+
+namespace Arcp.Core.Messages;
+
+/// <summary>Internal payload for the <c>arcp.invalid_envelope</c> sentinel emitted by a transport
+/// when a peer sends an envelope that fails to parse. Never transmitted over the wire; the
+/// dispatcher converts it into an outbound <c>session.error{INVALID_REQUEST}</c> per spec §12.</summary>
+public sealed record InvalidEnvelopePayload
+{
+    /// <summary>The parse-error message (truncated when logged so as not to echo arbitrary client
+    /// content back to peers in the error detail).</summary>
+    [JsonPropertyName("parse_error")] public required string ParseError { get; init; }
+}

src/Arcp.Core/Messages/MessageTypeNames.cs

@@ -33,6 +33,12 @@ public static class MessageTypeNames
     /// <summary>Gets the session resume.</summary>
     public const string SessionResume = "session.resume";
 
+    /// <summary>Sentinel emitted by a transport when an inbound envelope fails to deserialize.
+    /// The dispatcher converts this into an outbound <c>session.error{INVALID_REQUEST}</c> per
+    /// spec §12 so the misbehaving peer receives feedback instead of silent drop. Not transmitted
+    /// over the wire.</summary>
+    public const string InvalidEnvelope = "arcp.invalid_envelope";
+
     /// <summary>Gets the job submit.</summary>
     public const string JobSubmit = "job.submit";
     /// <summary>Gets the job accepted.</summary>

src/Arcp.Core/PublicAPI.Unshipped.txt

@@ -512,6 +512,12 @@ Arcp.Core.Messages.SessionPingPayload.Nonce.init -> void
 Arcp.Core.Messages.SessionPingPayload.SentAt.get -> System.DateTimeOffset
 Arcp.Core.Messages.SessionPingPayload.SentAt.init -> void
 Arcp.Core.Messages.SessionPingPayload.SessionPingPayload() -> void
+Arcp.Core.Messages.InvalidEnvelopePayload
+Arcp.Core.Messages.InvalidEnvelopePayload.<Clone>$() -> Arcp.Core.Messages.InvalidEnvelopePayload!
+Arcp.Core.Messages.InvalidEnvelopePayload.Equals(Arcp.Core.Messages.InvalidEnvelopePayload? other) -> bool
+Arcp.Core.Messages.InvalidEnvelopePayload.InvalidEnvelopePayload() -> void
+Arcp.Core.Messages.InvalidEnvelopePayload.ParseError.get -> string!
+Arcp.Core.Messages.InvalidEnvelopePayload.ParseError.init -> void
 Arcp.Core.Messages.SessionResumePayload
 Arcp.Core.Messages.SessionResumePayload.<Clone>$() -> Arcp.Core.Messages.SessionResumePayload!
 Arcp.Core.Messages.SessionResumePayload.Equals(Arcp.Core.Messages.SessionResumePayload? other) -> bool
@@ -716,6 +722,7 @@ const Arcp.Core.Messages.MessageTypeNames.SessionJobs = "session.jobs" -> string
 const Arcp.Core.Messages.MessageTypeNames.SessionListJobs = "session.list_jobs" -> string!
 const Arcp.Core.Messages.MessageTypeNames.SessionPing = "session.ping" -> string!
 const Arcp.Core.Messages.MessageTypeNames.SessionPong = "session.pong" -> string!
+const Arcp.Core.Messages.MessageTypeNames.InvalidEnvelope = "arcp.invalid_envelope" -> string!
 const Arcp.Core.Messages.MessageTypeNames.SessionResume = "session.resume" -> string!
 const Arcp.Core.Messages.MessageTypeNames.SessionWelcome = "session.welcome" -> string!
 const Arcp.Core.Messages.StatusPhases.CredentialRotated = "credential_rotated" -> string!
@@ -850,6 +857,9 @@ override Arcp.Core.Messages.SessionPingPayload.ToString() -> string!
 override Arcp.Core.Messages.SessionPongPayload.Equals(object? obj) -> bool
 override Arcp.Core.Messages.SessionPongPayload.GetHashCode() -> int
 override Arcp.Core.Messages.SessionPongPayload.ToString() -> string!
+override Arcp.Core.Messages.InvalidEnvelopePayload.Equals(object? obj) -> bool
+override Arcp.Core.Messages.InvalidEnvelopePayload.GetHashCode() -> int
+override Arcp.Core.Messages.InvalidEnvelopePayload.ToString() -> string!
 override Arcp.Core.Messages.SessionResumePayload.Equals(object? obj) -> bool
 override Arcp.Core.Messages.SessionResumePayload.GetHashCode() -> int
 override Arcp.Core.Messages.SessionResumePayload.ToString() -> string!
@@ -983,6 +993,8 @@ static Arcp.Core.Messages.SessionPingPayload.operator !=(Arcp.Core.Messages.Sess
 static Arcp.Core.Messages.SessionPingPayload.operator ==(Arcp.Core.Messages.SessionPingPayload? left, Arcp.Core.Messages.SessionPingPayload? right) -> bool
 static Arcp.Core.Messages.SessionPongPayload.operator !=(Arcp.Core.Messages.SessionPongPayload? left, Arcp.Core.Messages.SessionPongPayload? right) -> bool
 static Arcp.Core.Messages.SessionPongPayload.operator ==(Arcp.Core.Messages.SessionPongPayload? left, Arcp.Core.Messages.SessionPongPayload? right) -> bool
+static Arcp.Core.Messages.InvalidEnvelopePayload.operator !=(Arcp.Core.Messages.InvalidEnvelopePayload? left, Arcp.Core.Messages.InvalidEnvelopePayload? right) -> bool
+static Arcp.Core.Messages.InvalidEnvelopePayload.operator ==(Arcp.Core.Messages.InvalidEnvelopePayload? left, Arcp.Core.Messages.InvalidEnvelopePayload? right) -> bool
 static Arcp.Core.Messages.SessionResumePayload.operator !=(Arcp.Core.Messages.SessionResumePayload? left, Arcp.Core.Messages.SessionResumePayload? right) -> bool
 static Arcp.Core.Messages.SessionResumePayload.operator ==(Arcp.Core.Messages.SessionResumePayload? left, Arcp.Core.Messages.SessionResumePayload? right) -> bool
 static Arcp.Core.Messages.SessionWelcomePayload.operator !=(Arcp.Core.Messages.SessionWelcomePayload? left, Arcp.Core.Messages.SessionWelcomePayload? right) -> bool

src/Arcp.Core/Transport/StdioTransport.cs

@@ -6,6 +6,7 @@
 using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
+using Arcp.Core.Messages;
 using Arcp.Core.Wire;
 
 namespace Arcp.Core.Transport;
@@ -72,7 +73,11 @@ public async IAsyncEnumerable<Envelope> ReceiveAsync([EnumeratorCancellation] Ca
             }
             catch (Exception ex) when (ex is Errors.ArcpException or System.Text.Json.JsonException)
             {
-                continue;
+                env = new Envelope
+                {
+                    Type = MessageTypeNames.InvalidEnvelope,
+                    Payload = new InvalidEnvelopePayload { ParseError = ex.Message },
+                };
             }
             yield return env;
         }

src/Arcp.Core/Transport/WebSocketTransport.cs

@@ -8,6 +8,7 @@
 using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
+using Arcp.Core.Messages;
 using Arcp.Core.Wire;
 
 namespace Arcp.Core.Transport;
@@ -116,16 +117,22 @@ public async IAsyncEnumerable<Envelope> ReceiveAsync([EnumeratorCancellation] Ca
         {
             return ArcpJson.Deserialize(utf8);
         }
-        catch (Errors.ArcpException)
+        catch (Errors.ArcpException ex)
         {
-            return null;
+            return InvalidEnvelopeSentinel(ex.Message);
         }
-        catch (System.Text.Json.JsonException)
+        catch (System.Text.Json.JsonException ex)
         {
-            return null;
+            return InvalidEnvelopeSentinel(ex.Message);
         }
     }
 
+    private static Envelope InvalidEnvelopeSentinel(string parseError) => new()
+    {
+        Type = MessageTypeNames.InvalidEnvelope,
+        Payload = new InvalidEnvelopePayload { ParseError = parseError },
+    };
+
     /// <summary>Close (asynchronous).</summary>
     public async ValueTask CloseAsync(string? reason = null, CancellationToken cancellationToken = default)
     {

src/Arcp.Runtime/SessionState.Dispatch.cs

@@ -48,6 +48,11 @@ private async Task DispatchAsync(Envelope env, CancellationToken cancellationTok
     {
         switch (env.Type)
         {
+            case MessageTypeNames.InvalidEnvelope:
+                // Spec §12: surface INVALID_REQUEST to the peer so it gets feedback instead of
+                // a silent drop. Detail keeps the parse-error short to avoid echoing bytes back.
+                var parseError = (env.Payload as InvalidEnvelopePayload)?.ParseError ?? "malformed envelope";
+                throw new InvalidRequestException("Malformed ARCP envelope", parseError);
             case MessageTypeNames.SessionHello:
                 await HandleHelloAsync(env, cancellationToken).ConfigureAwait(false);
                 break;

tests/Arcp.IntegrationTests/SessionDispatchTests.cs

@@ -164,6 +164,37 @@ public async Task Subscriber_cannot_cancel_others_job()
         result.Success.Should().BeTrue();
     }
 
+    [Fact]
+    public async Task Malformed_envelope_yields_INVALID_REQUEST_session_error()
+    {
+        // Spec §12: malformed envelopes get explicit INVALID_REQUEST feedback (no silent drop).
+        // Transports surface a sentinel `arcp.invalid_envelope` envelope on parse failure; the
+        // dispatcher converts it into a `session.error{INVALID_REQUEST}` response.
+        var (server, transport) = StartServer(s =>
+            s.RegisterAgent("noop", (ctx, ct) => Task.FromResult<object?>(null)));
+
+        // Simulate a transport-level deserialization failure by sending the sentinel directly.
+        await transport.SendAsync(new Arcp.Core.Wire.Envelope
+        {
+            Type = MessageTypeNames.InvalidEnvelope,
+            Payload = new InvalidEnvelopePayload { ParseError = "test: not valid JSON" },
+        });
+
+        Arcp.Core.Wire.Envelope? err = null;
+        var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2));
+        try
+        {
+            await foreach (var env in transport.ReceiveAsync(cts.Token))
+            {
+                if (env.Type == MessageTypeNames.SessionError) { err = env; break; }
+            }
+        }
+        catch (OperationCanceledException) { }
+
+        err.Should().NotBeNull();
+        ((SessionErrorPayload)err!.Payload!).Code.Should().Be(ErrorCode.InvalidRequest);
+    }
+
     [Fact]
     public async Task SessionBye_closes_the_session_cleanly()
     {