docs: fix audit documentation issues (#48-66); format AuditFixesTests

nficano · cursoragent · nficano · commit 84c72075a822 · 2026-06-12T09:07:39.000-04:00
Correct XML comments, guides, OTel/conformance tables, and README for
all open docs audit findings. Fix dotnet format whitespace in integration tests.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/CONFORMANCE.md b/CONFORMANCE.md
@@ -69,7 +69,7 @@ Status legend: Implemented ✅ · Partial 🚧 · Not implemented ⛔.
 | ---- | ----------- | ------ | ----- |
 | §10  | `delegate` event kind on parent's `job.event` stream | ✅ | `JobContext.DelegateAsync` |
 | §11  | `trace_id` propagation; OTel span attrs | ✅ | `TraceAttributes`, `ArcpTracing.WithTracing` |
-| §11 (v1.1) | Span attrs `arcp.lease.expires_at`, `arcp.budget.remaining` | ✅ | `TraceAttributes` |
+| §11 (v1.1) | Span attrs `arcp.lease.expires_at`, `arcp.budget.remaining` | ❌ | Not emitted by `ArcpTracing` |
 | §12  | 15 canonical error codes with retryable booleans | ✅ | `ErrorCode.All`, `ErrorCode.IsRetryable` |
 
 ## Test cross-reference
diff --git a/README.md b/README.md
@@ -105,7 +105,7 @@ await using var client = await ArcpClient.ConnectAsync(transport, new ArcpClient
 
 var sessionId = client.SessionId;
 var resumeToken = client.ResumeToken;
-var effective = client.EffectiveFeatures; // intersection of client/runtime hello.features
+var effective = client.EffectiveFeatures; // intersection of hello.features and welcome.features
 
 // ... transport drops; track the last seq your reader observed ...
 var lastSeq = client.LastReceivedSeq;
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -9,7 +9,7 @@
 | `Arcp.Runtime`    | `ArcpServer`, `JobManager`, `LeaseManager`, `SessionState` — the side that runs them. |
 | `Arcp.AspNetCore` | Mounts a runtime on Kestrel via `IEndpointRouteBuilder.MapArcp("/arcp")`. |
 | `Arcp.Otel`       | Wraps `ITransport` with `ActivitySource`-based OTel instrumentation. |
-| `Arcp.Hosting`    | Registers a runtime in `IHostedService` for non-ASP.NET workers. |
+| `Arcp.Hosting`    | Registers `ArcpServer` in DI via `AddArcpRuntime` for non-ASP.NET workers. |
 | `Arcp.Cli`        | `arcp serve` / `arcp submit` / `arcp version` executable. |
 | `Arcp`            | Umbrella meta-package — `dotnet add package Arcp` pulls Core + Client + Runtime. |
 
@@ -37,12 +37,12 @@ Every message is a JSON object envelope:
 
 Unknown top-level fields are preserved verbatim in
 `Envelope.Extensions` (`Dictionary<string, JsonElement>`), so
-vendor-extension hints round-trip without loss (spec §5.1).
+vendor-extension hints round-trip without loss (spec §5).
 
 ## Versioning
 
 The SDK follows SemVer strictly. The `arcp` wire version field
-(`"1.1"`) is fixed in `Arcp.Core.WireVersion.Current`. Adding a
+defaults to `"1.1"` on `Envelope.Arcp` (also exposed as `Arcp.ArcpInfo.ProtocolVersion`). Adding a
 public member is a minor bump; changing a signature is a major bump.
 One minor deprecation cycle (`[Obsolete]`) before removal. See the
 [style guide](./style-guide.md#14-versioning--compatibility).
diff --git a/docs/conformance.md b/docs/conformance.md
@@ -60,7 +60,7 @@ Opt out of features on either peer:
 ```csharp
 new ArcpClientOptions
 {
-    Features = new FeatureSet(["heartbeat", "ack"]), // drop the rest
+    Features = new[] { FeatureFlags.Heartbeat, FeatureFlags.Ack }, // drop the rest
 };
 ```
 
diff --git a/docs/guides/errors.md b/docs/guides/errors.md
@@ -90,7 +90,7 @@ Agents can produce errors by throwing:
 ```csharp
 server.RegisterAgent("strict", async (ctx, ct) =>
 {
-    if (!ctx.Lease.Contains(LeaseNamespaces.FsRead))
+    if (ctx.Lease.Get(LeaseNamespaces.FsRead).Count == 0)
         throw new PermissionDeniedException("fs.read required");
 
     // ...
diff --git a/docs/guides/job-events.md b/docs/guides/job-events.md
@@ -27,11 +27,11 @@ server.RegisterAgent("researcher", async (ctx, ct) =>
     await ctx.StatusAsync("starting", "Fetching data...", ct);
 
     await ctx.ToolCallAsync("fetch", callId: "c1",
-        args: new { url = "https://api.example.com/data" }, ct);
+        args: new { url = "https://api.example.com/data" }, cancellationToken: ct);
     var data = /* ... */ "";
-    await ctx.ToolResultAsync("c1", result: data, ct);
+    await ctx.ToolResultAsync("c1", result: data, cancellationToken: ct);
 
-    await ctx.ProgressAsync(current: 1, total: 3, message: "fetched", ct);
+    await ctx.ProgressAsync(current: 1, total: 3, message: "fetched", cancellationToken: ct);
 
     await ctx.LogAsync("info", "Processing ...", ct);
     await ctx.MetricAsync("cost.inference", 0.012, unit: "USD", cancellationToken: ct);
@@ -40,7 +40,7 @@ server.RegisterAgent("researcher", async (ctx, ct) =>
         uri: "s3://bucket/report.pdf",
         contentType: "application/pdf",
         byteSize: 42_000,
-        ct: ct);
+        cancellationToken: ct);
 
     return new { status = "done" };
 });
diff --git a/docs/guides/leases.md b/docs/guides/leases.md
@@ -47,7 +47,7 @@ server.RegisterAgent("file-writer", async (ctx, ct) =>
             ctx.Lease,
             ctx.LeaseConstraints,
             LeaseNamespaces.FsWrite,
-            path: "/workspace/src/output.cs");
+            pattern: "/workspace/src/output.cs");
     }
     catch (PermissionDeniedException ex)
     {
diff --git a/docs/guides/observability.md b/docs/guides/observability.md
@@ -41,7 +41,7 @@ constants.
 | Name              | Purpose                                            |
 | ----------------- | -------------------------------------------------- |
 | `Arcp.Transport`  | One span per envelope (send and receive).          |
-| `Arcp.Runtime`    | Runtime-internal spans (dispatch, agent run).      |
+| `Arcp.Runtime`    | Application spans you start manually (e.g. delegation). |
 
 ## Span shape
 
@@ -66,10 +66,6 @@ For each envelope, the wrapper:
 | `arcp.job_id`              | envelope `job_id`                             |
 | `arcp.trace_id`            | envelope `trace_id`                           |
 | `arcp.event_seq`           | envelope `event_seq`                          |
-| `arcp.agent`               | `payload.agent` (on submit / accept)          |
-| `arcp.lease.capabilities`  | comma-joined lease keys                       |
-| `arcp.lease.expires_at`    | ISO 8601 string (v1.1)                        |
-| `arcp.budget.remaining`    | JSON-stringified currency map (v1.1)          |
 
 ## Use with ASP.NET Core
 
diff --git a/docs/guides/vendor-extensions.md b/docs/guides/vendor-extensions.md
@@ -31,8 +31,14 @@ Write on the send side by populating `Extensions` before calling
 `ITransport.SendAsync`:
 
 ```csharp
-var env = new Envelope { /* ... */ };
-env.Extensions["x-vendor.acme.priority"] = JsonSerializer.SerializeToElement("high");
+var env = new Envelope
+{
+    /* ... */
+    Extensions = new Dictionary<string, JsonElement>
+    {
+        ["x-vendor.acme.priority"] = JsonSerializer.SerializeToElement("high"),
+    },
+};
 await transport.SendAsync(env, ct);
 ```
 
diff --git a/docs/projects/Arcp.AspNetCore.md b/docs/projects/Arcp.AspNetCore.md
@@ -77,6 +77,6 @@ app.MapArcp(server, o => { o.Path = "/arcp-external";  o.AllowedHosts = new[] {
 
 - [Arcp.Runtime](./Arcp.Runtime.md) — `ArcpServer` configuration.
 - [Arcp.Otel](./Arcp.Otel.md) — transport instrumentation.
-- [Arcp.Hosting](./Arcp.Hosting.md) — `IHostedService` / DI integration.
+- [Arcp.Hosting](./Arcp.Hosting.md) — `AddArcpRuntime` DI registration.
 - [Troubleshooting — 403 Forbidden](../troubleshooting.md#websocket-upgrade-returns-403-forbidden) — allowed-host failures.
 - [Troubleshooting — HEARTBEAT_LOST](../troubleshooting.md#job-is-cancelled-with-heartbeat_lost) — keepalive collision.
diff --git a/docs/projects/Arcp.Core.md b/docs/projects/Arcp.Core.md
@@ -16,7 +16,7 @@ dotnet add package Arcp.Core
 The JSON container that wraps every ARCP message on the wire (spec §5):
 
 ```csharp
-public sealed class Envelope
+public sealed record Envelope
 {
     public string  Arcp       { get; init; }  // wire version, e.g. "1.1"
     public string  Id         { get; init; }  // random message id
@@ -25,10 +25,10 @@ public sealed class Envelope
     public string? JobId      { get; init; }
     public string? TraceId    { get; init; }
     public long?   EventSeq   { get; init; }
-    public JsonElement? Payload { get; init; }
+    public object? Payload    { get; init; }
 
     // Unknown top-level fields round-trip here (§15):
-    public Dictionary<string, JsonElement> Extensions { get; }
+    public IDictionary<string, JsonElement>? Extensions { get; init; }
 }
 ```
 
diff --git a/docs/projects/Arcp.Otel.md b/docs/projects/Arcp.Otel.md
@@ -73,10 +73,6 @@ For each envelope the wrapper:
 | `arcp.job_id`                | envelope `job_id`                        |
 | `arcp.trace_id`              | envelope `trace_id`                      |
 | `arcp.event_seq`             | envelope `event_seq`                     |
-| `arcp.agent`                 | `payload.agent` (on submit / accept)     |
-| `arcp.lease.capabilities`    | comma-joined lease keys                  |
-| `arcp.lease.expires_at`      | ISO 8601 string (v1.1)                   |
-| `arcp.budget.remaining`      | JSON-stringified currency map (v1.1)     |
 
 ## Propagating trace IDs to child jobs
 
diff --git a/docs/projects/Arcp.md b/docs/projects/Arcp.md
@@ -22,7 +22,7 @@ Optional add-ons are **not** bundled and must be referenced explicitly:
 | ------------------ | ----------------------------------------------------- |
 | `Arcp.AspNetCore`  | Kestrel / ASP.NET Core hosting (`MapArcp`).           |
 | `Arcp.Otel`        | OpenTelemetry transport instrumentation.              |
-| `Arcp.Hosting`     | `IHostedService` + `IHostApplicationLifetime` wiring. |
+| `Arcp.Hosting`     | `IServiceCollection.AddArcpRuntime` DI registration.    |
 | `Arcp.Cli`         | `arcp` CLI tool — serve and submit from a terminal.   |
 
 ## Typical project file
diff --git a/docs/recipes.md b/docs/recipes.md
@@ -50,7 +50,7 @@ intentionally drops the WebSocket connection mid-stream and reconnects using
 its `resume_token`. The runtime replays the missed chunks gap-free.
 
 Concepts: `ctx.BeginResultStream`, `ctx.WriteChunkAsync`, `handle.Chunks`,
-`ArcpClientOptions.ResumeToken`, `RESUME_WINDOW_EXPIRED`.
+`ArcpClient.ResumeToken`, `RESUME_WINDOW_EXPIRED`.
 
 → [`recipes/stream-resume/`](../recipes/stream-resume/)
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -110,7 +110,7 @@ trace ID). See
 
 An incoming envelope has a malformed payload. The most common cause is a
 version mismatch between the client and server SDK. Verify both sides use
-compatible `arcp` wire versions (`client.WireVersion` / `server.WireVersion`).
+compatible `arcp` wire versions (the envelope `arcp` field, default `"1.1"`).
 
 ### Vendor extension fields disappear
 
diff --git a/src/Arcp.Core/Envelope/Envelope.cs b/src/Arcp.Core/Envelope/Envelope.cs
@@ -6,7 +6,7 @@
 
 namespace Arcp.Core.Wire;
 
-/// <summary>The ARCP wire envelope (spec §5.1). Carries the message type discriminator, identifiers,
+/// <summary>The ARCP wire envelope (spec §5). Carries the message type discriminator, identifiers,
 /// and a payload object whose shape depends on <see cref="Type"/>.</summary>
 public sealed record Envelope
 {
@@ -56,7 +56,7 @@ public sealed record Envelope
     [JsonPropertyName("payload")]
     public object? Payload { get; init; }
 
-    /// <summary>Unknown top-level envelope fields preserved verbatim per spec §5.1 ("MUST ignore
+    /// <summary>Unknown top-level envelope fields preserved verbatim per spec §5 ("MUST ignore
     /// unknown fields") so they round-trip without loss.</summary>
     [JsonExtensionData]
     public IDictionary<string, JsonElement>? Extensions { get; init; }
diff --git a/src/Arcp.Core/Envelope/EnvelopeJsonConverter.cs b/src/Arcp.Core/Envelope/EnvelopeJsonConverter.cs
@@ -8,7 +8,7 @@ namespace Arcp.Core.Wire;
 
 /// <summary>Custom envelope (de)serializer. Reads the <c>type</c> field first to choose the
 /// concrete payload type from <see cref="MessageTypeRegistry"/>. Unknown <c>type</c> values produce
-/// an envelope with a <see cref="JsonElement"/> payload — they round-trip without loss per spec §5.1.</summary>
+/// an envelope with a <see cref="JsonElement"/> payload — they round-trip without loss per spec §5.</summary>
 public sealed class EnvelopeJsonConverter : JsonConverter<Envelope>
 {
     private readonly MessageTypeRegistry _registry;
@@ -101,9 +101,9 @@ private static EnvelopeFields ParseFields(JsonElement root)
     private static void ValidateHeader(EnvelopeFields fields)
     {
         if (string.IsNullOrEmpty(fields.Type))
-            throw new Errors.InvalidRequestException("Envelope missing required 'type' field (spec §5.1).");
+            throw new Errors.InvalidRequestException("Envelope missing required 'type' field (spec §5).");
         if (fields.Arcp is not null && fields.Arcp != "1.1")
-            throw new Errors.InvalidRequestException($"Unsupported ARCP envelope version: '{fields.Arcp}' (spec §5.1; expected '1.1').");
+            throw new Errors.InvalidRequestException($"Unsupported ARCP envelope version: '{fields.Arcp}' (spec §5; expected '1.1').");
     }
 
     private object? DeserializePayload(EnvelopeFields fields, JsonSerializerOptions options)
diff --git a/src/Arcp.Core/Errors/ErrorCode.cs b/src/Arcp.Core/Errors/ErrorCode.cs
@@ -48,8 +48,8 @@ public static class ErrorCode
         InvalidRequest, Unauthenticated, InternalError,
     }.ToFrozenSet();
 
-    /// <summary>Retryable codes per spec §12: only <c>AGENT_NOT_AVAILABLE</c>, <c>TIMEOUT</c>,
-    /// <c>HEARTBEAT_LOST</c>, and <c>INTERNAL_ERROR</c> may be retried.</summary>
+    /// <summary>Returns whether the code is in the spec §12 retryable set:
+    /// <c>AGENT_NOT_AVAILABLE</c>, <c>TIMEOUT</c>, <c>HEARTBEAT_LOST</c>, and <c>INTERNAL_ERROR</c>.</summary>
     public static bool IsRetryable(string code) => code is
         AgentNotAvailable or Timeout or HeartbeatLost or InternalError;
 }
diff --git a/src/Arcp.Core/Ids/Identifiers.cs b/src/Arcp.Core/Ids/Identifiers.cs
@@ -5,7 +5,7 @@
 
 namespace Arcp.Core.Ids;
 
-/// <summary>A ULID-based message identifier (envelope <c>id</c>, spec §5.1).</summary>
+/// <summary>A ULID-based message identifier (envelope <c>id</c>, spec §5).</summary>
 public readonly record struct MessageId(string Value) : IParsable<MessageId>
 {
     /// <summary>New.</summary>
diff --git a/tests/Arcp.IntegrationTests/AuditFixesTests.cs b/tests/Arcp.IntegrationTests/AuditFixesTests.cs
@@ -164,15 +164,17 @@ public async Task ListJobs_rejected_by_throwing_policy_surfaces_INTERNAL_ERROR()
         _ = Task.Run(() => server.AcceptAsync(aliceSrv));
         await using var alice = await ArcpClient.ConnectAsync(aliceT, new ArcpClientOptions
         {
-            Client = new ClientInfo { Name = "alice", Version = "1" }, Token = "alice",
+            Client = new ClientInfo { Name = "alice", Version = "1" },
+            Token = "alice",
         });
         await alice.SubmitAsync("sleeper");
 
         var (bobT, bobSrv) = MemoryTransport.Pair();
         _ = Task.Run(() => server.AcceptAsync(bobSrv));
         await using var bob = await ArcpClient.ConnectAsync(bobT, new ArcpClientOptions
         {
-            Client = new ClientInfo { Name = "bob", Version = "1" }, Token = "bob",
+            Client = new ClientInfo { Name = "bob", Version = "1" },
+            Token = "bob",
         });
 
         // bob listing forces ThrowingPolicy.CanObserve over alice's job → unexpected exception →

Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ Opt out of features on either peer:`
`60`	`60`	```csharp
`61`	`61`	`new ArcpClientOptions`
`62`	`62`	`{`
`63`		`- Features = new FeatureSet(["heartbeat", "ack"]), // drop the rest`
	`63`	`+ Features = new[] { FeatureFlags.Heartbeat, FeatureFlags.Ack }, // drop the rest`
`64`	`64`	`};`
`65`	`65`	```
`66`	`66`
Original file line number	Diff line number	Diff line change
`@@ -90,7 +90,7 @@ Agents can produce errors by throwing:`
`90`	`90`	```csharp
`91`	`91`	`server.RegisterAgent("strict", async (ctx, ct) =>`
`92`	`92`	`{`
`93`		`- if (!ctx.Lease.Contains(LeaseNamespaces.FsRead))`
	`93`	`+ if (ctx.Lease.Get(LeaseNamespaces.FsRead).Count == 0)`
`94`	`94`	`throw new PermissionDeniedException("fs.read required");`
`95`	`95`
`96`	`96`	`// ...`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ server.RegisterAgent("file-writer", async (ctx, ct) =>`
`47`	`47`	`ctx.Lease,`
`48`	`48`	`ctx.LeaseConstraints,`
`49`	`49`	`LeaseNamespaces.FsWrite,`
`50`		`- path: "/workspace/src/output.cs");`
	`50`	`+ pattern: "/workspace/src/output.cs");`
`51`	`51`	`}`
`52`	`52`	`catch (PermissionDeniedException ex)`
`53`	`53`	`{`