chore: align ARCP wire protocol version with v1.1

Nick Ficano · claude · Nick Ficano · commit b6dc5dfa0e33 · 2026-05-19T21:45:31.000-04:00
Bumps PROTOCOL_VERSION to "1.1" and refreshes the version.ts comments
to describe the literal value carried by the envelope. Updates source-
file headers, conformance docs, README badge/lede/wire-format table,
example READMEs, and inline wire-format snippets in the guides and
packages docs.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,4 +9,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial reference SDK release aligned with ARCP protocol v1.0 (see README status).
+- Initial reference SDK release aligned with ARCP protocol v1.1 (see README status).
diff --git a/CONFORMANCE.md b/CONFORMANCE.md
@@ -23,7 +23,7 @@ new v1.1 subsections appear after them.
 
 | Requirement                                                                                   | Status      | Location                                                                                                    |
 | --------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------- |
-| §5.1 `arcp` field, REQUIRED, MUST be `"1"` (unchanged in v1.1)                                | Implemented | `packages/core/src/version.ts:PROTOCOL_VERSION = "1"`; `packages/core/src/envelope.ts` rejects other values |
+| §5.1 `arcp` field, REQUIRED, MUST be `"1.1"`                                                  | Implemented | `packages/core/src/version.ts:PROTOCOL_VERSION = "1.1"`; `packages/core/src/envelope.ts` rejects other values |
 | §5.1 `id` REQUIRED, ULID/UUIDv7                                                               | Implemented | `packages/core/src/util/ulid.ts`; emitted by `buildEnvelope`                                                |
 | §5.1 `type` REQUIRED                                                                          | Implemented | `packages/core/src/envelope.ts`                                                                             |
 | §5.1 `session_id` REQUIRED on post-welcome envelopes                                          | Implemented | Per-message schemas in `packages/core/src/messages/{session,execution}.ts`                                  |
diff --git a/README.md b/README.md
@@ -2,9 +2,9 @@
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](#)
-[![ARCP](https://img.shields.io/badge/arcp-v1.0-orange.svg)](../spec/docs/draft-arcp-02.md)
+[![ARCP](https://img.shields.io/badge/arcp-v1.1-orange.svg)](../spec/docs/draft-arcp-02.md)
 
-Reference implementation of [ARCP v1.0](../spec/docs/draft-arcp-02.md), the
+Reference implementation of [ARCP v1.1](../spec/docs/draft-arcp-02.md), the
 Agent Runtime Control Protocol — a small wire protocol for letting an
 agent talk to the runtime that hosts it. ARCP is intentionally narrow:
 sessions, jobs, immutable per-job leases, a single event stream with
@@ -115,7 +115,7 @@ Every message on the wire is a JSON object with these required fields:
 
 | Field        | Meaning                                                                            |
 | ------------ | ---------------------------------------------------------------------------------- |
-| `arcp`       | Protocol version. v1.0 is the literal string `"1"`.                                |
+| `arcp`       | Protocol version. v1.1 is the literal string `"1.1"`.                                |
 | `id`         | Unique message id (ULID/UUIDv7).                                                   |
 | `type`       | Message type discriminator (e.g., `"job.submit"`).                                 |
 | `session_id` | REQUIRED on every envelope after `session.welcome`.                                |
@@ -327,7 +327,7 @@ await client.close();
 
 ## Conformance
 
-The SDK is intended to be 100% conforming to ARCP v1.0. Section-by-section
+The SDK is intended to be 100% conforming to ARCP v1.1. Section-by-section
 status lives in [`CONFORMANCE.md`](./CONFORMANCE.md).
 
 Spec sections implemented:
@@ -350,7 +350,7 @@ Twenty-three end-to-end examples, each a `server.ts` + `client.ts`
 pair that talks over a real `Transport`. See
 [`examples/README.md`](./examples/README.md):
 
-v1.0 core:
+Core:
 
 | Example              | Spec              |
 | -------------------- | ----------------- |
@@ -402,7 +402,7 @@ packages/
     hono/              # @arcp/hono
     bun/               # @arcp/bun
     otel/              # @arcp/middleware-otel
-examples/              # Twenty-three runnable two-process demos (v1.0 + v1.1 + host integrations)
+examples/              # Twenty-three runnable two-process demos (v1.1 + host integrations)
 diagrams/              # Graphviz .dot sources + rendered light/dark SVGs (see diagrams/README.md)
 ```
 
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -139,7 +139,7 @@ Every message is one JSON object with a small fixed envelope:
 
 | Field        | Required                                 | Notes                                                |
 | ------------ | ---------------------------------------- | ---------------------------------------------------- |
-| `arcp`       | always                                   | `"1"` for v1.0/v1.1                                  |
+| `arcp`       | always                                   | `"1.1"` (the v1.1 wire-format version literal)       |
 | `id`         | always                                   | ULID or UUIDv7, unique per message                   |
 | `type`       | always                                   | discriminator (`"session.hello"`, `"job.submit"`, …) |
 | `payload`    | always                                   | type-specific body                                   |
diff --git a/docs/conformance.md b/docs/conformance.md
@@ -1,11 +1,10 @@
 # Conformance
 
-The TypeScript SDK is intended to be 100% conforming to ARCP v1.0
-and includes opt-in v1.1 features. Section-by-section status lives
-in [`../CONFORMANCE.md`](../CONFORMANCE.md); this page is the docs
-mirror.
+The TypeScript SDK is intended to be 100% conforming to ARCP v1.1.
+Section-by-section status lives in
+[`../CONFORMANCE.md`](../CONFORMANCE.md); this page is the docs mirror.
 
-## v1.0 coverage
+## v1.1 coverage
 
 | Section                    | Status | Notes                                                              |
 | -------------------------- | ------ | ------------------------------------------------------------------ |
@@ -74,7 +73,7 @@ target.
 ## Reporting a deviation
 
 If you find behavior that disagrees with the
-[v1.0 spec](../../spec/docs/draft-arcp-02.md), open an issue with:
+[v1.1 spec](../../spec/docs/draft-arcp-1.1.md), open an issue with:
 
 - Section number.
 - Observed vs. expected behavior.
diff --git a/docs/guides/auth.md b/docs/guides/auth.md
@@ -1,6 +1,6 @@
 # Authentication (§6.1)
 
-ARCP v1.0 supports a single auth scheme: bearer tokens. The client
+ARCP v1.1 supports a single auth scheme: bearer tokens. The client
 sends a token in `session.hello`; the runtime verifies it via a
 `BearerVerifier` and binds the resulting identity to the session.
 
@@ -134,7 +134,7 @@ attachArcpUpgrade(httpServer, {
 
 ## Vendor auth extensions
 
-ARCP v1.0 reserves `authScheme: "bearer"` as the only standard value.
+ARCP v1.1 reserves `authScheme: "bearer"` as the only standard value.
 Custom schemes go through the `x-vendor.*` namespace:
 
 ```ts
diff --git a/docs/guides/observability.md b/docs/guides/observability.md
@@ -16,7 +16,7 @@ the runtime side starts a child span linked to the client's span.
 ```ts
 // envelope on the wire:
 {
-  arcp: "1",
+  arcp: "1.1",
   id: "01J…",
   type: "job.submit",
   trace_id: "0123456789abcdef0123456789abcdef",
diff --git a/docs/guides/vendor-extensions.md b/docs/guides/vendor-extensions.md
@@ -74,7 +74,7 @@ type AcmeWarmup = {
 
 // Client sends
 await client.send({
-  arcp: "1",
+  arcp: "1.1",
   id: newMessageId(),
   type: "x-vendor.acme.warmup",
   session_id: client.state.sessionId!,
@@ -111,7 +111,7 @@ Every envelope carries an optional `extensions` object:
 
 ```ts
 {
-  arcp: "1",
+  arcp: "1.1",
   id: "01J…",
   type: "job.submit",
   payload: { /* … */ },
diff --git a/docs/packages/client.md b/docs/packages/client.md
@@ -157,7 +157,7 @@ pressure their work if you need to.
 
 ```ts
 await client.send({
-  arcp: "1",
+  arcp: "1.1",
   id: newMessageId(),
   type: "x-vendor.acme.warmup",
   session_id: client.state.sessionId!,
diff --git a/docs/packages/core.md b/docs/packages/core.md
@@ -187,7 +187,7 @@ rules these helpers enforce.
 ```ts
 import {
   IMPL_VERSION,
-  PROTOCOL_VERSION, // "1"
+  PROTOCOL_VERSION, // "1.1"
   ProtocolVersion,
   intersectFeatures,
   isCompatibleVersion,
diff --git a/examples/README.md b/examples/README.md
@@ -1,12 +1,12 @@
 # ARCP TypeScript Examples
 
-Twenty-three end-to-end examples covering ARCP v1.0 and v1.1 plus the
+Twenty-three end-to-end examples covering ARCP v1.1 plus the
 host-integration middlewares. Each one is a pair of two processes — a
 runtime (`server.ts`) and a client (`client.ts`) — that talk over a
 real `Transport`. No mocks. No in-memory shortcuts. Each example exits
 0 on success.
 
-### v1.0 core
+### Core
 
 | Example                                      | Demonstrates                                                                                                                                                                                                                                         | Spec              |
 | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
diff --git a/examples/delegate/server.ts b/examples/delegate/server.ts
@@ -5,7 +5,7 @@
  *   - "build" (parent): runs a fake build, then delegates "test".
  *   - "test"  (child):  runs a fake test suite.
  *
- * Delegation in ARCP v1.0 is a `job.event` of kind "delegate" emitted
+ * Delegation in ARCP v1.1 is a `job.event` of kind "delegate" emitted
  * on the parent's stream. The runtime intercepts it, spawns a child
  * job in the same session, and the child's accept/events/result flow
  * through the same `event_seq` space — interleaved with the parent's.
diff --git a/examples/submit-and-stream/README.md b/examples/submit-and-stream/README.md
@@ -1,6 +1,6 @@
 # Submit and stream (two-process)
 
-The minimum useful ARCP v1.0 flow: a client submits a one-shot job to a
+The minimum useful ARCP v1.1 flow: a client submits a one-shot job to a
 runtime, the runtime streams events back, and the client prints them.
 
 This example demonstrates 7 of the 8 reserved `job.event` kinds in a
diff --git a/packages/core/src/brands.ts b/packages/core/src/brands.ts
@@ -10,7 +10,7 @@
  * keyed by the brand name). It carries no runtime weight, so values produced
  * by `as SessionId` / `as JobId` etc. round-trip cleanly through JSON.
  *
- * See ARCP v1.0 §5.1 (envelope `session_id`, `job_id`, `id`, `trace_id`,
+ * See ARCP v1.1 §5.1 (envelope `session_id`, `job_id`, `id`, `trace_id`,
  * `event_seq`) and §6.3 (`resume_token`).
  */
 
diff --git a/packages/core/src/envelope.ts b/packages/core/src/envelope.ts
@@ -10,7 +10,7 @@ import type {
 import { validateExtensionsObject } from "./extensions.js";
 import { PROTOCOL_VERSION } from "./version.js";
 
-// ARCP v1.0 §5.1 envelope: `arcp`, `id`, `type`, `session_id`, `trace_id`,
+// ARCP v1.1 §5.1 envelope: `arcp`, `id`, `type`, `session_id`, `trace_id`,
 // `job_id`, `event_seq`, `payload`, plus `extensions`.
 //
 //   - `arcp`        MUST be the literal `"1"`.
diff --git a/packages/core/src/extensions.ts b/packages/core/src/extensions.ts
@@ -1,6 +1,6 @@
 import { InvalidRequestError } from "./errors.js";
 
-// ARCP v1.0 extensions are `x-vendor.<vendor>.<name>` per §15 IANA notes.
+// ARCP v1.1 extensions are `x-vendor.<vendor>.<name>` per §15 IANA notes.
 // The old `arcpx.<vendor>.<name>.v<n>` namespace is gone.
 
 /**
@@ -26,7 +26,7 @@ export function isVendorExtensionName(
 }
 
 /**
- * Closed set of core v1.0 message types. Any other type must be in the
+ * Closed set of core v1.1 message types. Any other type must be in the
  * `x-vendor.*` namespace.
  */
 export const CORE_MESSAGE_TYPES = [
@@ -47,7 +47,7 @@ const CORE_TYPE_SET: ReadonlySet<string> = new Set(CORE_MESSAGE_TYPES);
 
 const CORE_PREFIXES = ["session.", "job."] as const;
 
-/** Whether `type` is one of the ten core ARCP v1.0 message types. */
+/** Whether `type` is one of the ten core ARCP v1.1 message types. */
 export function isCoreType(type: string): type is CoreMessageType {
   return CORE_TYPE_SET.has(type);
 }
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -1,5 +1,5 @@
 // Public surface of @arcp/core — shared primitives consumed by @arcp/client
-// and @arcp/runtime. See ARCP v1.0 for the protocol spec.
+// and @arcp/runtime. See ARCP v1.1 for the protocol spec.
 
 export * from "./auth/index.js";
 export type {
diff --git a/packages/core/src/messages/artifacts.ts b/packages/core/src/messages/artifacts.ts
@@ -1,7 +1,7 @@
 import { Schema } from "effect";
 
-// ARCP v1.0 §8.2 — `artifact_ref` event kind body shape only. There is no
-// top-level artifact envelope in v1.0; agents emit a `job.event` with
+// ARCP v1.1 §8.2 — `artifact_ref` event kind body shape only. There is no
+// top-level artifact envelope in v1.1; agents emit a `job.event` with
 // `kind = "artifact_ref"` and the body shape below.
 
 /**
diff --git a/packages/core/src/messages/events.ts b/packages/core/src/messages/events.ts
@@ -6,7 +6,7 @@ import { ArtifactRefSchema } from "./artifacts.js";
 import { LeaseConstraintsSchema } from "./lease-schema.js";
 import { LogPayloadSchema, MetricPayloadSchema } from "./telemetry.js";
 
-// ARCP v1.0 §8 + v1.1 §8.2/§8.4 — `job.event` body schemas.
+// ARCP v1.1 §8 / §8.2 / §8.4 — `job.event` body schemas.
 //
 // This module owns the per-kind body schemas and the `parseJobEventBody`
 // dispatch over the reserved-kind set. Bodies for `log`, `metric`, and
diff --git a/packages/core/src/messages/execution.ts b/packages/core/src/messages/execution.ts
@@ -10,7 +10,7 @@ import {
 import { JobEventPayloadSchema } from "./events.js";
 import { LeaseConstraintsSchema, LeaseSchema } from "./lease-schema.js";
 
-// ARCP v1.0 §7-§8 job-related envelopes.
+// ARCP v1.1 §7-§8 job-related envelopes.
 
 export {
   isReservedCapabilityName,
diff --git a/packages/core/src/messages/index.ts b/packages/core/src/messages/index.ts
@@ -1,5 +1,5 @@
 /**
- * Aggregate registry of every core message type defined by ARCP v1.0/v1.1.
+ * Aggregate registry of every core message type defined by ARCP v1.1.
  *
  * `EnvelopeSchema` is the discriminated union over `type` (Effect Schema).
  * Parsing an inbound envelope through this schema yields a fully-typed
diff --git a/packages/core/src/messages/session.ts b/packages/core/src/messages/session.ts
@@ -3,7 +3,7 @@ import { Schema } from "effect";
 import { messageEnvelope } from "../envelope.js";
 import { ErrorPayloadSchema } from "../errors.js";
 
-// ARCP v1.0 + v1.1 session envelopes (§6):
+// ARCP v1.1 session envelopes (§6):
 //   session.hello     — client → runtime; opens a new or resumed session.
 //   session.welcome   — runtime → client; issued on accepted hello.
 //   session.error     — runtime → client; rejection or fatal session-level error.
diff --git a/packages/core/src/messages/telemetry.ts b/packages/core/src/messages/telemetry.ts
@@ -1,7 +1,7 @@
 import { Schema } from "effect";
 
-// ARCP v1.0 §8.2 — body shapes used by `job.event` payloads for `kind=log`
-// and `kind=metric`. There are no top-level telemetry envelopes in v1.0.
+// ARCP v1.1 §8.2 — body shapes used by `job.event` payloads for `kind=log`
+// and `kind=metric`. There are no top-level telemetry envelopes in v1.1.
 
 export const LOG_LEVELS = [
   "trace",
diff --git a/packages/core/src/state/session.ts b/packages/core/src/state/session.ts
@@ -11,7 +11,7 @@ import type { Capabilities } from "../messages/types.js";
 
 import type { SessionPhase, SessionSnapshot } from "./types.js";
 
-// ARCP v1.0 session lifecycle. Phases:
+// ARCP v1.1 session lifecycle. Phases:
 //
 //   opening   — pre-welcome
 //   accepted  — post-welcome, live
diff --git a/packages/core/src/state/types.ts b/packages/core/src/state/types.ts
@@ -5,7 +5,7 @@ import type { Capabilities } from "../messages/types.js";
 /**
  * Phases of a single ARCP session.
  *
- * @see ARCP v1.0 §6.
+ * @see ARCP v1.1 §6.
  */
 export type SessionPhase = "opening" | "accepted" | "closing" | "rejected";
 
diff --git a/packages/core/src/store/eventlog.ts b/packages/core/src/store/eventlog.ts
@@ -19,13 +19,13 @@ import type { EventLogFilter, EventLogOptions } from "./types.js";
 
 type DatabaseInstance = InstanceType<typeof Database>;
 
-// ARCP v1.0 event-log indexed columns: session_id, id, type, trace_id,
+// ARCP v1.1 event-log indexed columns: session_id, id, type, trace_id,
 // job_id, event_seq. Replay is by (session_id, event_seq).
 
 /**
  * Append-only SQLite event log.
  *
- * Idempotent appends per (session_id, id) per ARCP v1.0 §5.1.
+ * Idempotent appends per (session_id, id) per ARCP v1.1 §5.1.
  * Replay is by `event_seq` per §6.3 / §8.3.
  *
  * The underlying `better-sqlite3` driver is synchronous; this class wraps
diff --git a/packages/core/src/store/schema.ts b/packages/core/src/store/schema.ts
@@ -5,5 +5,5 @@ import { fileURLToPath } from "node:url";
 
 const SCHEMA_PATH = fileURLToPath(new URL("schema.sql", import.meta.url));
 
-/** The ARCP v1.0 event-log DDL. Idempotent (`CREATE TABLE IF NOT EXISTS`). */
+/** The ARCP v1.1 event-log DDL. Idempotent (`CREATE TABLE IF NOT EXISTS`). */
 export const SCHEMA_SQL: string = readFileSync(SCHEMA_PATH, "utf8");
diff --git a/packages/core/src/util/ulid.ts b/packages/core/src/util/ulid.ts
@@ -9,7 +9,7 @@ const factory = monotonicFactory();
  * Mint a fresh monotonic ULID for use as an envelope `id`.
  *
  * Monotonic within a process under fast clock skew. Lexically sortable.
- * @see ARCP v1.0 §5.1 (`id` field semantics).
+ * @see ARCP v1.1 §5.1 (`id` field semantics).
  */
 export function newId(prefix?: string): string {
   const ulid = factory();
diff --git a/packages/core/src/version.ts b/packages/core/src/version.ts
@@ -1,12 +1,12 @@
 /**
  * Protocol version implemented by this package.
  *
- * Tracks ARCP v1.1 (additive over v1.0). The `arcp` envelope field is the
- * literal major-version string per §5.1; v1.1 keeps this at `"1"` and uses
- * the feature-negotiation capability in `session.hello`/`session.welcome`
- * to detect what each peer supports.
+ * Tracks ARCP v1.1 (additive over v1.0). The `arcp` envelope field carries
+ * the full protocol version per §5.1. Peers also exchange a
+ * `capabilities.features` list in `session.hello`/`session.welcome` to
+ * negotiate which v1.1 additive features each side supports.
  */
-export const PROTOCOL_VERSION = "1" as const;
+export const PROTOCOL_VERSION = "1.1" as const;
 
 /** Implementation version of this package. Bump on releases. */
 export const IMPL_VERSION = "0.2.0" as const;
@@ -44,8 +44,8 @@ export type ProtocolVersion = typeof PROTOCOL_VERSION;
 /**
  * Whether `other` is wire-compatible with this implementation.
  *
- * v1.1 stays at `arcp: "1"` literally — the wire-format major did not
- * change between v1.0 and v1.1. Feature negotiation happens through the
+ * Compares the `arcp` literal against [`PROTOCOL_VERSION`]. Additive v1.1
+ * feature differences are negotiated separately through the
  * `capabilities.features` array.
  */
 export function isCompatibleVersion(other: string): boolean {
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
@@ -1,4 +1,4 @@
-// Public surface of @arcp/runtime. See ARCP v1.0.
+// Public surface of @arcp/runtime. See ARCP v1.1.
 export {
   negotiateCapabilities,
   type PendingMeta,
diff --git a/packages/runtime/src/job.ts b/packages/runtime/src/job.ts
@@ -26,7 +26,7 @@ export interface JobDependencies {
   readonly logger: Logger;
 }
 
-// ARCP v1.0 §7-§8 job execution.
+// ARCP v1.1 §7-§8 job execution.
 //
 // State machine: pending → running → {success | error | cancelled | timed_out}.
 // All event-bearing envelopes (job.event / job.result / job.error) carry a
diff --git a/packages/runtime/src/lease.ts b/packages/runtime/src/lease.ts
@@ -14,7 +14,7 @@ import {
 
 import type { LeaseOpContext } from "./types.js";
 
-// ARCP v1.0 §9 — leases.
+// ARCP v1.1 §9 — leases.
 //
 // A lease is an immutable record granted to a job at submission. It maps
 // capability names to lists of glob patterns. Enforcement is the runtime's
diff --git a/packages/sdk/src/cli.ts b/packages/sdk/src/cli.ts

Original file line number	Diff line number	Diff line change
`@@ -9,4 +9,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`
`9`	`9`
`10`	`10`	`### Added`
`11`	`11`
`12`		`-- Initial reference SDK release aligned with ARCP protocol v1.0 (see README status).`
	`12`	`+- Initial reference SDK release aligned with ARCP protocol v1.1 (see README status).`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ the runtime side starts a child span linked to the client's span.`
`16`	`16`	```ts
`17`	`17`	`// envelope on the wire:`
`18`	`18`	`{`
`19`		`- arcp: "1",`
	`19`	`+ arcp: "1.1",`
`20`	`20`	`id: "01J…",`
`21`	`21`	`type: "job.submit",`
`22`	`22`	`trace_id: "0123456789abcdef0123456789abcdef",`