refactor SDK structure

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

Author: nficano

.refactor/baseline.md

@@ -0,0 +1,51 @@
+# Refactor Baseline (pre-work)
+
+Captured: 2026-05-14
+
+## Tests
+
+- 139 passed, 3 skipped, 0 failed
+- Coverage: 73.27% (gate target: 90%)
+- Skipped tests are intentional documented races (see `tests/state/`)
+
+## Ruff
+
+- `ruff check .` — **0 violations** (with current ruleset)
+- `ruff format --check .` — **0 files would change**
+
+## Mypy strict
+
+- 14 errors across 8 files (after installing mypy)
+- Categories:
+  - 4× `no-any-return` at Pydantic `.model_dump()`/typed-dict boundaries
+  - 2× missing `arcp.ARCPClient`/`StaticBearerVerifier` re-exports for CLI
+  - 1× server `EventLog`/`InMemoryEventLog` Liskov mismatch
+  - 1× server `_subscribe` missing `await` on async iter call
+  - 1× client `Job*Payload` Liskov mismatch
+  - 1× CLI `event_log` argument typing
+  - misc unused-ignore / name-defined
+
+## Hard-limit violations (Guide §0)
+
+### Files > 300 lines
+- `src/arcp/_runtime/server.py` — 744
+- `src/arcp/_client/client.py` — 479
+- `src/arcp/_runtime/job.py` — 372
+- `src/arcp/_messages/execution.py` — 348
+
+### Functions > 5 args / complexity > 8
+- `src/arcp/_auth/jwt.py:16` — `JWTVerifier.__init__` (7 args)
+- `src/arcp/_client/client.py:69` — `ARCPClient.__init__` (7 args)
+- `src/arcp/_client/client.py:183` — `submit` (8 args)
+- `src/arcp/_client/client.py:291` — `_handshake` (11 args)
+- `src/arcp/_runtime/server.py:110` — `ARCPRuntime.__init__` (>5 args)
+- `src/arcp/_runtime/server.py:340` — `_dispatch` (complexity 11)
+- `src/arcp/_runtime/server.py:532` — `_run_job` (complexity 11)
+- `src/arcp/_runtime/session.py:150` — `make_session_state` (6 args)
+
+### Other inventory
+- `__all__` missing: `cli.py`, `__main__.py` (both are CLI entry points — acceptable)
+- `from __future__ import annotations` missing on a few `__init__.py` shims (acceptable; they have no annotations)
+- `setup.py` / `setup.cfg`: none (PEP 621 already)
+- `src/` layout: ✓ already
+- `py.typed` marker: present

.refactor/public_api.md

@@ -0,0 +1,57 @@
+# Public API Surface (pre-refactor)
+
+Captured from `__all__` in `src/arcp/__init__.py`, `src/arcp/client/__init__.py`,
+and `src/arcp/runtime/__init__.py`. **No symbol below may be removed or
+renamed without a major bump.**
+
+## `arcp` (top-level)
+
+### Envelope
+- `Envelope`
+
+### Errors
+- `ARCPError`, `ERROR_CODES`, `error_class_for`, `error_from_payload`
+- `AgentNotAvailableError`, `AgentVersionNotAvailableError`,
+  `BudgetExhaustedError`, `CancelledError`, `DuplicateKeyError`,
+  `HeartbeatLostError`, `InternalError`, `InvalidRequestError`,
+  `JobNotFoundError`, `LeaseExpiredError`, `LeaseSubsetViolationError`,
+  `PermissionDeniedError`, `ResumeWindowExpiredError`, `TimeoutError`,
+  `UnauthenticatedError`
+
+### Messages
+- `Capabilities`, `ClientInfo`, `Lease`, `LeaseConstraints`,
+  `ListJobsFilter`, `RuntimeInfo`, `SessionResume`,
+  `SessionWelcomePayload`
+- `parse_agent_ref`, `parse_budget_amount`
+
+### Transports
+- `Transport`, `TransportClosed`, `MemoryTransport`,
+  `pair_memory_transports`, `StdioTransport`, `WebSocketTransport`,
+  `serve_websocket`
+
+### Version / features
+- `PROTOCOL_VERSION`, `IMPL_VERSION`, `V1_1_FEATURES`,
+  `intersect_features`
+
+## `arcp.client`
+- `ARCPClient`, `AutoAckOptions`, `JobHandle`, `JobSubscription`
+
+## `arcp.runtime`
+- `ARCPRuntime`, `AuthorizationContext`, `JobAuthorizationPolicy`
+- `Agent`, `Job`, `JobContext`, `ResultStream`
+- `SessionContext`, `SessionState`
+- `BearerVerifier`, `Identity`, `StaticBearerVerifier`, `JWTVerifier`
+- `EventLog`, `InMemoryEventLog`, `SqliteEventLog`
+- `LeaseOpContext`, `assert_lease_subset`, `initial_budget_from_lease`,
+  `is_lease_subset`, `validate_lease_constraints`,
+  `validate_lease_op`, `validate_lease_shape`
+
+## CLI entry point
+- `arcp` (console script → `arcp.cli:main`)
+
+## Notes
+- The CLI imports `ARCPClient`/`StaticBearerVerifier` from `arcp` top-level
+  (mypy flags this as missing). They are *not* re-exported there today;
+  the CLI relies on the dynamic re-export chain. Honor either by
+  (a) keeping CLI internal, or (b) adding top-level re-exports. Choice
+  documented in CHANGELOG.

.refactor/violations.md

@@ -0,0 +1,73 @@
+# Violations Inventory
+
+## File length > 300 lines (Guide §0)
+
+| File                                | Lines | Plan                                                  |
+| ----------------------------------- | ----- | ----------------------------------------------------- |
+| `src/arcp/_runtime/server.py`       | 744   | Split: lifecycle / dispatch / job-run / housekeeping |
+| `src/arcp/_client/client.py`        | 479   | Split: connection / handshake / job ops              |
+| `src/arcp/_runtime/job.py`          | 372   | Split: data classes vs. ResultStream impl            |
+| `src/arcp/_messages/execution.py`   | 348   | Split: payload models / helpers / parsers            |
+
+## Function-level violations (`ruff --select C901,PLR0913,PLR0912`)
+
+| Location                                   | Issue                          | Plan                                |
+| ------------------------------------------ | ------------------------------ | ----------------------------------- |
+| `_auth/jwt.py:16` JWTVerifier.__init__     | 7 args                         | Group into `JWTVerifierConfig` dc   |
+| `_client/client.py:69` ARCPClient.__init__ | 7 args                         | Group into `ClientConfig` dc        |
+| `_client/client.py:183` submit             | 8 args                         | Group into `JobSubmit` dc           |
+| `_client/client.py:291` _handshake         | 11 args                        | Group into `HandshakeArgs` dc       |
+| `_runtime/server.py:110` __init__          | >5 args                        | Group into `RuntimeConfig` dc       |
+| `_runtime/server.py:340` _dispatch         | complexity 11                  | Dict-of-handlers                    |
+| `_runtime/server.py:532` _run_job          | complexity 11                  | Extract phases                      |
+| `_runtime/session.py:150` make_session_state | 6 args                       | Group into `SessionParams` dc       |
+
+## Mypy --strict errors (14 total)
+
+| Location                                | Issue                                          | Plan                                 |
+| --------------------------------------- | ---------------------------------------------- | ------------------------------------ |
+| `middleware/asgi.py:48`                 | Any return on model_dump()                     | `cast(dict[str, Any], ...)`          |
+| `middleware/aiohttp.py:43`              | same                                           | same                                 |
+| `_transport/stdio.py:38`                | same                                           | same                                 |
+| `_transport/websocket.py:46`            | same                                           | same                                 |
+| `_transport/websocket.py:67`            | Any return on int|None                         | explicit cast                        |
+| `_transport/websocket.py:86`            | `Server` name-defined (TYPE_CHECKING)          | proper import guard                  |
+| `_messages/execution.py:67`             | unused type:ignore                             | drop comment                         |
+| `_client/client.py:213`                 | Liskov: payload class union narrowing          | use match/cast                       |
+| `_client/client.py:366`                 | Any return                                     | explicit cast                        |
+| `_runtime/server.py:135`                | `EventLog|InMemoryEventLog` vs `EventLog`      | hoist InMemoryEventLog into hierarchy |
+| `_runtime/server.py:679`                | missing await on async iter                    | `async for x in await coro`          |
+| `cli.py:13`                             | missing top-level `ARCPClient`                 | import from `arcp.client`            |
+| `cli.py:13`                             | missing top-level `StaticBearerVerifier`       | import from `arcp.runtime`           |
+| `cli.py:48`                             | event_log subtype mismatch                     | widen param type                     |
+
+## Coverage (60% → 90% target)
+
+Currently 73.27%. Largest gaps:
+- `_runtime/server.py` 68%
+- `_runtime/session.py` 57%
+- `_transport/base.py` 63%
+- `_transport/in_memory.py` 84%
+- `_envelope.py` (check)
+
+## Other inventory
+
+- `print()` in library code: **none** (verified)
+- bare `except`: **none** (verified)
+- wildcard imports: **none** (verified)
+- mutable default args: **none flagged by ruff**
+- `Optional`/`Union` style: **none** (verified — already uses `X | None`)
+- `setup.py`/`setup.cfg`: **none**
+- `py.typed`: **present**
+- src layout: **present**
+
+## Decisions for documented judgment calls
+
+1. **`coverage --cov-fail-under=60` → 90.** The guide mandates 90.
+   Bump in the same PR.
+2. **`ruff.lint.mccabe.max-complexity` not configured.** Set to 8.
+3. **`ruff.lint.pylint.max-args` not configured.** Set to 5.
+4. **`pyright` is in `pyproject.toml` (strict).** Add `mypy --strict`
+   alongside, keep pyright for IDEs.
+5. **Doctests:** add `--doctest-modules` to default pytest invocation.
+6. **`pre-commit`:** add config invoking ruff + mypy.