docs: align spec citations, paths, and stubs with the v1.1 workspace

Sweeps documentation drift surfaced by the spec-vs-SDK audit. No code
behavior changes — only doc comments, markdown, and the changelog.

- RFC section refs corrected to ARCP v1.1 throughout (§8→§6 sessions,
  §10→§7 jobs, §13→§7.6 subscribe, §15→§9 leases, §18→§12 errors,
  §22→§4 transport; §11.3/§17/§19/§21 had no v1.1 analog and are
  removed or re-anchored). SDK extensions beyond v1.1 (the
  challenge/authenticate auth flow, signed_jwt/none auth schemes, the
  x-… and arcpx.* extension namespaces, the artifact store, interrupt,
  Priority) are now flagged as such instead of pretending to cite a
  spec section.
- Broken doc paths fixed: src/* → crates/<crate>/src/* across
  docs/architecture.md, docs/transports.md, docs/guides/errors.md,
  docs/guides/jobs.md.
- docs/architecture.md and docs/README.md rewritten to describe the
  actual Cargo workspace (umbrella arcp + arcp-core/client/runtime +
  four reservation stubs) rather than the old "single arcp crate"
  layout; feature flag table gains client/runtime rows; persistence
  section notes runtime feature gating.
- docs/getting-started.md, examples/README.md, README.md: bump the
  install snippet from arcp = "1.1" / "1" to "2"; soften the
  "runnable" claim on examples that elide setup with todo!().
- CHANGELOG.md gains a 2.0.0 entry covering the workspace split and
  the reservation stubs.
- CONFORMANCE.md §6.6 row downgraded to Partial — the runtime
  implements list_jobs/job.subscribe but the client API does not yet
  expose them as first-class Session methods; the publish dry-run
  gate is updated to iterate the eight workspace crates.
- Reservation stub crates (arcp-tower, arcp-axum, arcp-actix-web,
  arcp-otel) docs now explicitly state they ship no integration
  types and do not depend on tower/axum/actix-web/opentelemetry, so
  consumers don't install expecting middleware they don't get.
- README license footer updated to MIT OR Apache-2.0 to match
  Cargo.toml; CONTRIBUTING WebSocket port matches the CLI default
  127.0.0.1:7777.
- docs/guides/job-events.md adds an explicit "spec §8.2 kind" column
  next to the SDK wire type column so readers can map between the
  spec's job.event kind enum and the SDK's top-level Job* variants.
- README, CONTRIBUTING, and docs/guides/vendor-extensions.md flag
  the SDK's session.open / session.accepted as the wire serialization
  of the spec's §6.2 session.hello / session.welcome envelopes.
- recipes/README.md is honest about the recipes not being wired as
  examples, and points readers at adapting the snippets.

Spec-conformance findings that require API changes (rename SessionOpen
→ SessionHello, add resume_token / heartbeat_interval_sec to the
welcome payload, restructure the top-level Job* variants into a
kind-tagged JobEvent enum, lease expiration enforcement, credential
rotation, JobState terminal set, etc.) are intentionally out of scope
for this commit. The full audit is at audit-findings.json /
audit-findings.md (kept untracked).

Verified locally:
  cargo check --workspace --all-targets
  cargo clippy --workspace --all-targets -- -D warnings
  cargo fmt --all -- --check
  cargo test --workspace --doc

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Nick Ficano <nficano@gmail.com>

Author: nficano

CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+The Rust SDK is a Cargo workspace; the version recorded here tracks
+`workspace.package.version` in [`Cargo.toml`](Cargo.toml) and applies to the
+co-released `arcp`, `arcp-core`, `arcp-client`, and `arcp-runtime` crates.
+The middleware reservation stubs (`arcp-tower`, `arcp-axum`,
+`arcp-actix-web`, `arcp-otel`) are versioned independently at
+`0.1.0-alpha.0`.
+
+## [2.0.0] - 2026-05
+
+### Changed
+
+- Restructured the single `arcp` crate into a Cargo workspace ahead of 2.0
+  publish: the umbrella `arcp` crate now re-exports `arcp-core` (wire types,
+  IDs, transports, error taxonomy), `arcp-client` (`ARCPClient` + type-state
+  `Session`), and `arcp-runtime` (`ARCPRuntime`, SQLite event log, JWT/bearer
+  auth, `arcp` CLI). Direct consumers can pull individual crates to slim
+  dependencies.
+
+### Added
+
+- Reservation stubs for forthcoming middleware: `arcp-tower`, `arcp-axum`,
+  `arcp-actix-web`, `arcp-otel`. These crates publish at `0.1.0-alpha.0`
+  and currently re-export `arcp-core` only.
+
 ## [0.1.0] - 2026-05-10
 
 ### Added

CONFORMANCE.md

@@ -14,7 +14,7 @@ The docs mirror is [`docs/conformance.md`](./docs/conformance.md).
 | §6.3 Resume | Full | SQLite event log supports replay by session and sequence boundary; resumability examples exercise reconnect flows. |
 | §6.4 Heartbeat | Full | `session.ping` / `session.pong` messages and runtime examples are implemented. |
 | §6.5 Ack | Full | Runtime ack window and `session.ack` back-pressure are implemented. |
-| §6.6 List jobs / Subscribe | Full | `session.list_jobs`, `job.subscribe`, `job.unsubscribe`, and generic subscription fanout are implemented. |
+| §6.6 List jobs / Subscribe | Partial | Runtime: `session.list_jobs`, `job.subscribe`, `job.unsubscribe`, and generic subscription fanout are implemented. Client API does not yet expose `list_jobs`/`job.subscribe` as first-class `Session` methods. |
 | §7 Jobs | Full | Submit, accept, start, complete, fail, cancel, state inventory, and idempotent retry paths. |
 | §7.3 State machine | Full | `JobRegistry` tracks pending, running, and terminal states. |
 | §7.4 Cancellation | Full | Cooperative cancellation uses `CancellationToken` and emits cancelled terminal outcomes. |
@@ -47,10 +47,13 @@ Before release, run:
 
 ```sh
 cargo fmt --all -- --check
-cargo check --all-targets --all-features
-cargo test --all-features
-cargo clippy --all-targets --all-features -- -D warnings
-cargo publish --dry-run
+cargo check --workspace --all-targets --all-features
+cargo test --workspace --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+# Publish dry-run iterates the workspace in dependency order:
+for crate in arcp-core arcp-client arcp-runtime arcp arcp-tower arcp-axum arcp-actix-web arcp-otel; do
+    cargo publish --dry-run -p "$crate"
+done
 ```
 
 ## Deferred Surfaces

CONTRIBUTING.md

@@ -31,9 +31,10 @@ Concretely:
 - **Don't invent wire behavior.** No envelope fields, event kinds, error codes,
   or feature flags that the spec doesn't define. If you need one, it's a spec
   proposal first.
-- **Negotiate honestly.** Only advertise a feature flag in `session.hello` once
-  the SDK actually implements it. The feature matrix in the README must match
-  what the code negotiates — a row marked `Supported` is a promise.
+- **Negotiate honestly.** Only advertise a feature flag in `SessionOpen` (the
+  SDK's serialization of the spec's `session.hello`) once the SDK actually
+  implements it. The feature matrix in the README must match what the code
+  negotiates — a row marked `Supported` is a promise.
 - **Respect the semantics.** Sequence numbers stay gap-free and monotonic;
   `LEASE_EXPIRED` and `BUDGET_EXHAUSTED` stay non-retryable; the effective
   feature set is the intersection of client and runtime advertisements. Tests
@@ -85,8 +86,9 @@ Two layers must pass before a PR merges:
   error mapping) needs a test that exercises the real exchange, not a mock that
   assumes the answer. Integration tests under [`tests/`](tests/) drive the
   in-process runtime end to end; to point them at an out-of-process runtime,
-  start one with `cargo run -- serve --bearer secret-token --principal alice@example.com`
-  and connect the WebSocket transport at `ws://127.0.0.1:8765`. See
+  start one with `cargo run --bin arcp -- serve --bearer secret-token --principal alice@example.com`
+  and connect the WebSocket transport at `ws://127.0.0.1:7777` (the CLI default
+  bind; pass `--bind 127.0.0.1:8765` to use a different port). See
   [`CONFORMANCE.md`](CONFORMANCE.md) for the section-by-section coverage matrix.
 
 CI runs both on every PR. A PR that changes which feature flags the SDK

README.md

@@ -6,7 +6,7 @@
   <a href="https://github.com/agentruntimecontrolprotocol/rust-sdk/actions/workflows/test.yml"><img alt="CI" src="https://github.com/agentruntimecontrolprotocol/rust-sdk/actions/workflows/test.yml/badge.svg"></a>
   <a href="https://codecov.io/gh/agentruntimecontrolprotocol/rust-sdk"><img alt="codecov" src="https://codecov.io/gh/agentruntimecontrolprotocol/rust-sdk/graph/badge.svg"></a>
   <a href="https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md"><img alt="ARCP" src="https://img.shields.io/badge/ARCP-v1.1%20draft-blue"></a>
-  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-lightgrey"></a>
+  <a href="LICENSE-APACHE"><img alt="License" src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-lightgrey"></a>
 </p>
 
 <p align="center">
@@ -123,7 +123,7 @@ This is the whole shape of the SDK: open a session, submit work, consume an orde
 
 ARCP organizes everything around four concerns — **identity**, **durability**, **authority**, and **observability** — expressed through five core objects:
 
-- **Session** — a connection between a client and a runtime. A session carries identity (a bearer token), negotiates a feature set in a `hello`/`welcome` handshake, and is *resumable*: if the transport drops, you reconnect with a resume token and the runtime replays buffered events. Jobs outlive the session that started them. See [§6](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
+- **Session** — a connection between a client and a runtime. A session carries identity (a bearer token), negotiates a feature set in a hello/welcome handshake (the SDK serializes these as `SessionOpen`/`SessionAccepted`), and is *resumable*: if the transport drops, you reconnect with a resume token and the runtime replays buffered events. Jobs outlive the session that started them. See [§6](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
 - **Job** — one unit of agent work submitted into a session. A job has an identity, an optional idempotency key, a resolved agent version, and a lifecycle that ends in exactly one terminal state: `success`, `error`, `cancelled`, or `timed_out`. See [§7](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
 - **Event** — the ordered, session-scoped stream a job emits: logs, thoughts, tool calls and results, status, metrics, artifact references, progress, and streamed result chunks. Events carry strictly monotonic sequence numbers so the stream survives reconnects gap-free. See [§8](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
 - **Lease** — the authority a job runs under, expressed as capability grants (`fs.read`, `fs.write`, `net.fetch`, `tool.call`, `agent.delegate`, `cost.budget`, `model.use`). The runtime enforces the lease at every operation boundary; a job can never act outside it. Leases may carry a budget and an expiry, and may be subset and handed to sub-agents via delegation. See [§9](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
@@ -399,12 +399,12 @@ Full API reference — every type, method, and event payload — is in [`docs/`]
 
 ## Versioning and compatibility
 
-This SDK speaks **ARCP v1.1 (draft)**. The SDK follows semantic versioning independently of the protocol; the protocol version it negotiates is shown above and in `session.hello`. A runtime advertising a different ARCP MAJOR is not guaranteed compatible. Feature mismatches degrade gracefully: the effective feature set is the intersection of what the client and runtime advertise, and the SDK will not use a feature outside it.
+This SDK speaks **ARCP v1.1 (draft)**. The SDK follows semantic versioning independently of the protocol; the protocol version it negotiates is shown above and in the `SessionOpen` envelope (which the spec names `session.hello`). A runtime advertising a different ARCP MAJOR is not guaranteed compatible. Feature mismatches degrade gracefully: the effective feature set is the intersection of what the client and runtime advertise, and the SDK will not use a feature outside it.
 
 ## Contributing
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md). Protocol questions and proposed changes belong in the [spec repository](https://github.com/agentruntimecontrolprotocol/spec); SDK bugs and feature requests belong here.
 
 ## License
 
-Apache-2.0 — see [`LICENSE`](LICENSE).
+Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or [MIT license](LICENSE-MIT) at your option.

crates/arcp-actix-web/src/lib.rs

@@ -1,16 +1,13 @@
 //! # arcp-actix-web
 //!
-//! actix-web integration for the Agent Runtime Control Protocol (ARCP).
+//! Name reservation for a planned actix-web integration. **This crate
+//! currently provides no actix types**; it does not depend on `actix-web`.
+//! It only re-exports [`arcp_core`] so dependents can prepare imports
+//! against a stable crate name.
 //!
-//! ## Status: placeholder
-//!
-//! This crate is published as a name reservation. A real actix-web
-//! integration — handler factory, WebSocket upgrade, and `ARCPRuntime`
-//! adapter — is planned for a future minor release. The current version
-//! re-exports [`arcp_core`] so dependents can prepare imports.
-//!
-//! Follow <https://github.com/agentruntimecontrolprotocol/rust-sdk> for
-//! progress.
+//! A real actix-web integration — handler factory, WebSocket upgrade, and
+//! `ARCPRuntime` adapter — is planned for a future minor release. Follow
+//! <https://github.com/agentruntimecontrolprotocol/rust-sdk> for progress.
 
 #![deny(unsafe_code)]
 #![deny(missing_docs)]

crates/arcp-axum/src/lib.rs

@@ -1,16 +1,15 @@
 //! # arcp-axum
 //!
-//! axum integration for the Agent Runtime Control Protocol (ARCP).
+//! Name reservation for a planned axum integration. **This crate currently
+//! provides no axum types**; it does not depend on `axum`. It only
+//! re-exports [`arcp_core`] so dependents can prepare imports against a
+//! stable crate name.
 //!
-//! ## Status: placeholder
-//!
-//! This crate is published as a name reservation. A real axum integration
-//! — Router, WebSocket upgrade handler, and `ARCPRuntime` extractor — is
-//! planned for a future minor release. The current version re-exports
-//! [`arcp_core`] so dependents can prepare imports.
-//!
-//! In the meantime, an end-to-end axum + ARCP server example lives at
-//! [`examples/axum_server.rs`][example] in the umbrella crate.
+//! A real axum integration — Router, WebSocket upgrade handler, and
+//! `ARCPRuntime` extractor — is planned for a future minor release. Until
+//! then, see [`crates/arcp/examples/axum_server.rs`][example] in the
+//! umbrella crate for a hand-rolled axum-plus-ARCP pattern that uses
+//! `axum` directly rather than anything in this crate.
 //!
 //! [example]: https://github.com/agentruntimecontrolprotocol/rust-sdk/blob/main/crates/arcp/examples/axum_server.rs
 

crates/arcp-client/src/api.rs

@@ -1,4 +1,8 @@
-//! `ARCPClient` and the type-state [`Session<S>`] (RFC §4.6, §8).
+//! `ARCPClient` and the type-state [`Session<S>`].
+//!
+//! Implements the client side of the ARCP v1.1 §6.2 hello/welcome handshake
+//! (serialized as `session.open` / `session.accepted`) and §7 job lifecycle
+//! over an `arcp-core` [`Transport`][arcp_core::transport::Transport].
 
 use std::marker::PhantomData;
 use std::sync::Arc;
@@ -103,7 +107,10 @@ impl<S: sealed::State, T: Transport + 'static> std::fmt::Debug for Session<S, T>
 }
 
 impl<T: Transport + 'static> Session<Unauthenticated, T> {
-    /// Drive the four-step handshake (RFC §8.1) and, on success, return a
+    /// Drive the ARCP v1.1 §6.2 hello/welcome handshake (serialized by the
+    /// SDK as `session.open` / `session.accepted`, with an optional
+    /// SDK-extension challenge / authenticate pair between them when the
+    /// configured authenticator requests it) and, on success, return a
     /// [`Session<Authenticated>`].
     ///
     /// On success a background reader task is spawned to dispatch incoming
@@ -362,7 +369,7 @@ impl<T: Transport + 'static> Session<Authenticated, T> {
 
     /// Invoke a tool by name. Returns a [`JobHandle`] the caller can await
     /// for the terminal result, and which carries the runtime-assigned
-    /// [`JobId`] once `job.accepted` arrives (RFC §10).
+    /// [`JobId`] once `job.accepted` arrives (ARCP v1.1 §7).
     ///
     /// # Errors
     ///
@@ -421,7 +428,9 @@ impl<T: Transport + 'static> Session<Authenticated, T> {
         })
     }
 
-    /// Upload an artifact (RFC §16.2). Returns the canonical
+    /// Upload an artifact (SDK extension; ARCP v1.1 §8.2 defines an
+    /// `artifact_ref` event kind but no `artifact.*` envelope surface).
+    /// Returns the canonical
     /// [`ArtifactRef`] the runtime minted.
     ///
     /// `data` must be base64-encoded; the caller is responsible for
@@ -507,7 +516,8 @@ impl<T: Transport + 'static> Session<Authenticated, T> {
         }
     }
 
-    /// Release (delete) an artifact (RFC §16.2). The runtime does not
+    /// Release (delete) an artifact (SDK extension; see the `put_artifact`
+    /// note above). The runtime does not
     /// acknowledge releases; this is fire-and-forget.
     ///
     /// # Errors
@@ -522,8 +532,11 @@ impl<T: Transport + 'static> Session<Authenticated, T> {
         self.inner.transport.send(env).await
     }
 
-    /// Subscribe to runtime events (RFC §13). Returns a
-    /// [`SubscriptionHandle`] yielding live envelopes that match `filter`.
+    /// Subscribe to runtime events via the SDK's generic filtered subscription
+    /// bus. (For per-job subscription as defined by ARCP v1.1 §7.6, see
+    /// `JobSubscribePayload`; that surface is not yet exposed as a first-class
+    /// `Session` method.) Returns a [`SubscriptionHandle`] yielding live
+    /// envelopes that match `filter`.
     ///
     /// # Errors
     ///
@@ -568,7 +581,8 @@ impl<T: Transport + 'static> Session<Authenticated, T> {
     }
 }
 
-/// Handle to a live subscription (RFC §13).
+/// Handle to a live subscription (see the SDK's generic subscription bus;
+/// per-job subscription is ARCP v1.1 §7.6).
 ///
 /// Dropping the handle removes the client-side forwarder and stops local
 /// delivery; it does **not** send an `unsubscribe` envelope. Call
@@ -639,7 +653,7 @@ fn map_nack(p: NackPayload) -> ARCPError {
     }
 }
 
-/// Handle to an in-flight job (RFC §10).
+/// Handle to an in-flight job (ARCP v1.1 §7).
 pub struct JobHandle {
     /// Server-assigned job identifier.
     pub job_id: JobId,

crates/arcp-client/src/lib.rs

@@ -2,8 +2,9 @@
 //!
 //! Ships [`ARCPClient`] and the type-state [`Session`] for opening,
 //! authenticating, and driving a session over any
-//! [`Transport`][arcp_core::transport::Transport]. Job, stream, and
-//! subscription handles hang off `Session<Authenticated>`.
+//! [`Transport`][arcp_core::transport::Transport]. Job and subscription
+//! handles hang off `Session<Authenticated>`; raw streams are surfaced via
+//! subscription events rather than a dedicated stream handle.
 //!
 //! Wire-format types are re-exported from `arcp-core` for ergonomics; most
 //! users should pull in the umbrella `arcp` crate which bundles client +

crates/arcp-core/src/auth/mod.rs

@@ -1,9 +1,15 @@
-//! Authentication scheme adapters (RFC §8.2).
+//! Authentication scheme adapters.
 //!
-//! Each [`Authenticator`] implementation validates one auth scheme. The
-//! runtime composes these into an [`AuthRegistry`]; on `session.open` the
+//! ARCP v1.1 §6.1 collapses authentication to a single bearer token carried
+//! in `session.hello.payload.auth.token` (the SDK serializes this envelope as
+//! `session.open`). The [`Authenticator`] trait is an SDK extension that
+//! lets a runtime support additional schemes (`signed_jwt`, `none`, etc.) —
+//! including a legacy challenge / response flow not described by v1.1 — by
+//! composing implementations into an [`AuthRegistry`]; on `session.open` the
 //! runtime dispatches by [`AuthScheme`] and either accepts directly or
 //! issues a [`session.challenge`][crate::messages::SessionChallengePayload].
+//! Bearer is the only scheme normative under v1.1; the others are SDK
+//! extensions outside the spec surface.
 
 use std::collections::HashMap;