docs: align session/replay docs with shipped behavior; add YARD + agent-versioning guide

The previous docs and gemspec promised transparent session resume with a
SQLite-backed event log. The SDK actually ships in-memory event buffering
with replay via `subscribe_job(history: true, from_event_seq: ...)`, and
the resume-token wiring is not finished. Update README, CONFORMANCE,
architecture, recipes, and the sessions/resume/leases/jobs/troubleshooting
guides to describe what we actually ship, and mark §6.3 transparent
resume as deferred.

Also add YARD-style docstrings to the public Client, Job::Handle, Lease,
Runtime, EventLog, and AgentInventory surfaces, refresh the module-deps
diagrams, and add a new agent-versioning guide.

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

Author: nficano

CONFORMANCE.md

@@ -18,7 +18,7 @@ v1.0.0). No spec MUST/SHOULD in §4–§16 is unimplemented.
 | §6.2 Capability negotiation (intersection) | yes | `lib/arcp/session/capability_set.rb#intersect` |
 | §6.2 Feature names: heartbeat, ack, list_jobs, subscribe, lease_expires_at, cost.budget, progress, result_chunk, agent_versions, model.use, provisioned_credentials | yes | `lib/arcp/session/feature.rb` |
 | §6.3 session.welcome with resume_token + resume_window_sec | yes | `lib/arcp/session/welcome.rb`, `lib/arcp/runtime/session_actor.rb` |
-| §6.3 Resume by last_event_seq | yes | `lib/arcp/runtime/event_log.rb` |
+| §6.3 Resume by last_event_seq | deferred | n/a |
 | §6.4 session.ping / session.pong heartbeats | yes | `lib/arcp/session/ping.rb`, `lib/arcp/session/pong.rb`, `lib/arcp/client.rb#start_heartbeat!` |
 | §6.4 HEARTBEAT_LOST MUST NOT terminate jobs | yes | `lib/arcp/runtime/session_actor.rb` |
 | §6.5 session.ack with last_processed_seq | yes | `lib/arcp/session/ack.rb`, `lib/arcp/client.rb#ack` |

README.md

@@ -27,7 +27,7 @@ ARCP itself is a transport-agnostic wire protocol for long-running AI agent jobs
 
 ## Installation
 
-Requires Ruby 3.3 or later. The gem runs on the `socketry/async` reactor and pulls in `async-websocket` for the default networked transport and `sqlite3` for the resume log; no separate extras are needed. Add it to a `Gemfile`:
+Requires Ruby 3.3 or later. The gem runs on the `socketry/async` reactor and pulls in `async-websocket` for the default networked transport. The runtime currently buffers events in memory for replay; durable persistence is not shipped yet. Add it to a `Gemfile`:
 
 ```ruby
 gem 'arcp', '~> 1.0'
@@ -83,7 +83,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, and keeps a replay window in the runtime's in-memory event log. Transparent reconnect resume is not wired through yet; use `history: true` and `from_event_seq` when you need to replay 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).
@@ -93,9 +93,9 @@ The SDK models each of these as first-class objects; the rest of this README sho
 
 ## Guides
 
-### Sessions and resume
+### Sessions and replay
 
-Open a session, negotiate features, and reconnect transparently after a transport drop using the resume token — jobs keep running server-side while you're gone.
+Open a session, submit work, and replay buffered events from the retained log window when you need to recover missed history.
 
 ```ruby
 require 'async'
@@ -108,22 +108,15 @@ Sync do
     client_name: 'resumable'
   )
 
-  session_id   = client.session.id
-  resume_token = client.session.resume_token
-  last_seq     = Hash.new(0)
   handle = client.submit_job(agent: 'long-runner')
   handle.subscribe(client: client).each do |event|
-    last_seq[handle.job_id] = event.body.respond_to?(:seq) ? event.body.seq : last_seq[handle.job_id]
+    puts "#{event.kind}: #{event.body.to_h}"
   end
 
-  # ... transport drops ...
-
-  resumed = Arcp::Client.open(
-    transport: new_transport,
-    auth: { 'scheme' => 'bearer', 'token' => ENV.fetch('ARCP_TOKEN') },
-    resume: { 'token' => resume_token, 'last_event_seq' => last_seq }
-  )
-  # The runtime replays every event with event_seq > last_seq, then resumes live streaming.
+  replay = client.subscribe_job(job_id: handle.job_id, from_event_seq: 0, history: true)
+  replay.each do |event|
+    puts "[replay] #{event.kind}"
+  end
 end
 ```
 
@@ -277,7 +270,7 @@ 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 negotiated runtime version is available on `client.session.runtime_version`. 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
 

arcp.gemspec

@@ -11,9 +11,9 @@ Gem::Specification.new do |spec|
   spec.summary     = 'Reference Ruby implementation of the Agent Runtime Control Protocol (ARCP).'
   spec.description = <<~DESC
     Ruby SDK for ARCP: envelope and message model, fiber-based runtime, client,
-    WebSocket / stdio / in-memory transports, SQLite-backed resume log,
-    capability negotiation, leases with budget and expiration, streamed results,
-    and OpenTelemetry trace propagation. Built on socketry/async.
+    WebSocket / stdio / in-memory transports, in-memory event buffering for
+    replay, capability negotiation, leases with budget and expiration, streamed
+    results, and OpenTelemetry trace propagation. Built on socketry/async.
   DESC
   spec.homepage    = 'https://github.com/nficano/arpc'
   spec.license     = 'Apache-2.0'

docs/architecture.md

@@ -46,7 +46,7 @@ Arcp
     JobContext            # passed to handlers
     LeaseManager          # lease + budget accounting
     SubscriptionManager   # cross-session observers
-    EventLog              # replay window
+    EventLog              # in-memory replay window
   Transport
     Base / MemoryTransport / WebSocketTransport / StdioTransport
 ```
@@ -113,7 +113,7 @@ Arcp::Session::Feature::RESULT_CHUNK      # 'result_chunk'
 Arcp::Session::Feature::AGENT_VERSIONS    # 'agent_versions'
 ```
 
-`Arcp::Session::Feature::ALL` is a frozen Array of all nine.
+`Arcp::Session::Feature::ALL` is a frozen Array of all eleven.
 
 ### Negotiation
 
@@ -163,8 +163,8 @@ client.submit_job(agent: 'code-refactor@1.0.0')  # pins to 1.0.0
 ```
 
 An unknown version raises `Arcp::Errors::AgentVersionNotAvailable` with
-`details['available_versions']` populated. `AgentInventory#resolve(ref)`
-can validate a ref before submit:
+`details['available']` populated. `AgentInventory#resolve(ref)` can
+validate a ref before submit:
 
 ```ruby
 client.session.capabilities.agents.resolve('code-refactor@1.0.0')

docs/diagrams/module-deps-dark.dot

@@ -86,7 +86,7 @@ digraph ArcpModuleDeps {
     SubMgr  [label="SubscriptionManager"];
 
     EventLog [
-      label=<<FONT POINT-SIZE="10">EventLog</FONT><BR/><FONT POINT-SIZE="8" COLOR="#64748B">SQLite</FONT>>,
+      label=<<FONT POINT-SIZE="10">EventLog</FONT><BR/><FONT POINT-SIZE="8" COLOR="#64748B">In-memory</FONT>>,
       shape=cylinder, fillcolor="#1E293B"
     ];
   }

docs/diagrams/module-deps-dark.svg

@@ -88,7 +88,7 @@ digraph ArcpModuleDeps {
     SubMgr  [label="SubscriptionManager"];
 
     EventLog [
-      label=<<FONT POINT-SIZE="10">EventLog</FONT><BR/><FONT POINT-SIZE="8" COLOR="#94A3B8">SQLite</FONT>>,
+      label=<<FONT POINT-SIZE="10">EventLog</FONT><BR/><FONT POINT-SIZE="8" COLOR="#94A3B8">In-memory</FONT>>,
       shape=cylinder, fillcolor="#FAFBFC"
     ];
   }

docs/diagrams/module-deps-light.dot

@@ -0,0 +1,50 @@
+---
+title: Agent versioning
+sdk: ruby
+kind: guide
+order: 13
+spec_sections: [§7.5]
+---
+
+# Agent versioning
+
+Agents are registered under a stable name and an optional set of
+published versions. When a client submits `name@version`, the runtime
+resolves that exact version if it exists; when the client submits only
+`name`, the runtime uses the registered default.
+
+## Register versions
+
+```ruby
+runtime.register_agent(
+  name: 'code-refactor',
+  versions: %w[1.0.0 2.0.0],
+  default: '2.0.0',
+  handler: ->(ctx) { ctx.finish(result: ctx.agent) }
+)
+```
+
+## Submit a version-pinned job
+
+```ruby
+handle = client.submit_job(agent: 'code-refactor@1.0.0')
+result = handle.get_result(client: client)
+```
+
+## Validate a ref first
+
+`Arcp::Session::AgentInventory#resolve(ref)` returns the normalized
+`name@version` string or `nil` if the ref is unknown. On failure, the
+runtime raises `Arcp::Errors::AgentVersionNotAvailable` with
+`details['available']` populated with the registered versions.
+
+```ruby
+inventory = client.session.capabilities.agents
+inventory.resolve('code-refactor@1.0.0') # => "code-refactor@1.0.0"
+inventory.resolve('code-refactor@9.9.9') # => nil
+```
+
+## See also
+
+- `guides/sessions.md`
+- `guides/jobs.md`

docs/diagrams/module-deps-light.svg

@@ -107,8 +107,9 @@ HANDLER = lambda do |ctx|
 end
 ```
 
-`try_spend!` atomically decrements the lease's `BudgetCounter`. If the
-balance goes negative, the runtime emits `job.error` with code
+`Arcp::Runtime::LeaseManager#try_spend!` atomically decrements the
+lease's `BudgetCounter` by calling `BudgetCounter#try_decrement`. If the
+balance is insufficient, the runtime emits `job.error` with code
 `BUDGET_EXHAUSTED`.
 
 When spend is enforced by an upstream gateway instead of local counters,
@@ -121,7 +122,7 @@ issued key — see `guides/credentials.md`.
 begin
   handle.get_result(client: client)
 rescue Arcp::Errors::BudgetExhausted => e
-  e.details # { 'currency' => 'USD', 'requested' => ..., 'remaining' => ... }
+  e.details # { 'currency' => 'USD', 'remaining' => '0.30' }
 end
 ```