@@ -16,10 +16,13 @@ gh api repos/ably/specification/contents/uts/docs/integration-testing.md --jq '.
 gh api repos/ably/specification/contents/uts/rest/unit/<spec>.md --jq '.content' | base64 -d
 gh api repos/ably/specification/contents/uts/realtime/unit/<spec>.md --jq '.content' | base64 -d
 gh api repos/ably/specification/contents/uts/rest/integration/<spec>.md --jq '.content' | base64 -d
+gh api repos/ably/specification/contents/uts/docs/proxy.md --jq '.content' | base64 -d
+gh api repos/ably/specification/contents/uts/rest/integration/proxy/<spec>.md --jq '.content' | base64 -d
 ```
 
 `writing-derived-tests.md` governs, and `integration-testing.md` alongside it for
-`uts/rest/integration`. This file covers only what is particular to ably-python.
+`uts/rest/integration`, with `proxy.md` governing the proxy package within it. This
+file covers only what is particular to ably-python.
 
 ## Layout
 
@@ -285,9 +288,10 @@ All in `test.uts.helpers.clock`.
 ## The integration tier
 
 `uts/rest/integration/<name>.md` becomes `test/uts/rest/integration/<name>_test.py` and
-runs against the real Ably sandbox — eleven specifications, 76 tests. There is no mock
-and no `_test_options`: the client reaches the network. `test/uts/README.md` covers the
-same ground for someone reading the suite; this is what someone writing a test needs.
+runs against the real Ably sandbox — twelve specifications, 84 tests, one of them the
+proxy package the section below covers. There is no mock and no `_test_options`: the
+client reaches the network. `test/uts/README.md` covers the same ground for someone
+reading the suite; this is what someone writing a test needs.
 
 What differs from the mock-backed tiers:
 
@@ -333,6 +337,86 @@ async def test_rsl2a_history_returns_messages(sandbox, use_binary_protocol):
     history = await wall_clock_poll_until(one_message, description='the message to reach history')
 ```
 
+## The proxy tier
+
+`uts/rest/integration/proxy/<name>.md` becomes
+`test/uts/rest/integration/proxy/<name>_test.py`, and routes its traffic through
+[ably/uts-proxy](https://github.com/ably/uts-proxy) on the way to the sandbox. The
+proxy binds a port per session, takes plain HTTP on it, speaks TLS onwards, applies the
+session's rules and records what crosses it. `uts/docs/proxy.md` governs the tier and
+is worth reading in full before deriving one of these; fetch it the same way as the
+other governing docs.
+
+What differs from the rest of the integration tier:
+
+- **The client points at the session, not at the sandbox.** `endpoint='localhost'`,
+  `port=session.proxy_port`, `tls=False`, `use_binary_protocol=False`. `endpoint` and
+  `port` set the primary host, and `fallback_hosts=['localhost']` sets the fallback to
+  the same session, so both attempts land in one event log. Leave `fallback_hosts` out
+  where the spec does: `endpoint='localhost'` disables fallbacks by itself (REC2c2).
+- **Authentication is a callback.** A plain connection cannot carry basic auth, so
+  every client takes `auth_callback=`; see the traps below.
+- **A fault is a rule, and everything else passes through.** `times: 1` faults the
+  first request that matches and lets the retry reach the sandbox, which is the shape
+  every fallback scenario wants.
+- **The proxy is the second witness.** The SDK's own result answers half the question
+  and `session.get_log()` the other half — how many requests were made, in what order,
+  and what the proxy answered them with.
+- **The per-test timeout is 300 seconds**, set by the package's own `conftest.py`.
+
+| Name | Is |
+|---|---|
+| `proxy_session` fixture, in `rest/integration/proxy/conftest.py` | a specification's `create_proxy_session(...)`, together with its `AFTER EACH TEST: session.close()`. `session = await proxy_session(rules=[...])`, as many times as a test needs, and every session is closed afterwards |
+| `proxy_control` fixture | the running control API, session-scoped. `proxy_session` asks for it, so a test does not have to |
+| `create_proxy_session(endpoint=SANDBOX_ENDPOINT, port=None, rules=None, timeout_ms=SESSION_TIMEOUT_MS)` | the function itself, in `test.uts.helpers.proxy`, for the rare case that wants a session the fixture will not close |
+| `session.session_id`, `session.proxy_host`, `session.proxy_port` | what a spec reads off its `session`. The host is always `localhost` |
+| `session.add_rules(rules, position='append')` | rules added while the session runs. `position='prepend'` puts them ahead of the ones already there, which is how a spec faults traffic only once the client has reached some state |
+| `session.trigger_action(action)` | the imperative half — `{'type': 'disconnect'}`, `{'type': 'close', 'closeCode': 1000}`, `inject_to_client`. 409 from the control API when no connection is open |
+| `session.get_log()` | every event, in order, as the dictionaries the control API sends: `type`, `method`, `path`, `status`, `direction`, `queryParams`, `message`, `ruleMatched`. The field names are the ones a specification's assertions are written against, so they are not renamed |
+| `session.close()` | best effort and never raises; the fixture calls it for you |
+| `ensure_proxy()` / `stop_proxy()` | start the control process and reap it. Only the `proxy_control` fixture should need them |
+| `PROXY_VERSION`, `ARCHIVE_CHECKSUMS`, `RELEASE_URL` | the pinned release and the sha256 of each platform's archive. Moving the pin means new checksums, copied from the release's own `checksums.txt` |
+| `SESSION_TIMEOUT_MS` (120000) | the session's **idle** auto-cleanup timer, passed as `timeoutMs` |
+| `SUITE_TIMEOUT` (300) in the package `conftest.py` | the per-test timeout for this package |
+| `UTS_PROXY_LOCAL_PATH` | a locally built binary, or a `.tar.gz` holding one, in place of the pinned release |
+| `UTS_PROXY_CONTROL_URL` | a control API already running, which is then neither started nor stopped by the suite |
+
+Everything but the two fixtures is in `test.uts.helpers.proxy`. `http_requests` and
+`http_responses` in the example below are the derived file's own log filters, defined
+at the top of it, because every test in the file reads the log the same two ways.
+
+```python
+# UTS: rest/proxy/RSC15l4/cloudfront-header-fallback-0
+async def test_rsc15l4_cloudfront_header_fallback(sandbox, proxy_session):
+    session = await proxy_session(rules=[{
+        'match': {'type': 'http_request', 'pathContains': '/time'},
+        'action': {
+            'type': 'http_respond',
+            'status': 403,
+            'body': {'error': {'message': 'Forbidden', 'code': 40300, 'statusCode': 403}},
+            'headers': {'Server': 'CloudFront'},
+        },
+        'times': 1,
+        'comment': 'RSC15l4: CloudFront 403 on first /time request',
+    }])
+
+    client = sandbox_rest_client(
+        auth_callback=token_auth_callback(sandbox.key_str),
+        endpoint='localhost',
+        fallback_hosts=['localhost'],
+        port=session.proxy_port,
+        tls=False,
+        use_binary_protocol=False,
+    )
+
+    result = await client.time()
+    assert isinstance(result, (int, float))
+
+    log = await session.get_log()
+    assert len(http_requests(log, '/time')) >= 2
+    assert http_responses(log)[0]['status'] == 403
+```
+
 ## Traps that cost the most time
 
 Ordered by how much they cost, not by subject. Every one was hit for real while
@@ -594,6 +678,61 @@ that **passes while proving nothing**, rather than one that fails.
   Use `wall_clock_poll_until`, and no `FakeClock`. `writing-derived-tests.md` has a
   section on this ("Integration timeouts are wall-clock").
 
+## Traps found while deriving the proxy tier
+
+Established against the real proxy and the real sandbox while deriving
+`rest/integration/proxy/rest_fallback.md`.
+
+- **Basic auth cannot be used through the proxy at all.** The session speaks plain
+  HTTP, and `tls=False` makes the SDK raise `40103 "Cannot use Basic Auth over non-TLS
+  connections"` (RSC18) before a request is written, so a client built with `key=`
+  never reaches a rule. `client.time()` is the one call that works, because it is
+  `skip_auth`. Every test in the specification therefore authenticates with
+  `authCallback`, including the `/time` ones, and a derived test should keep that even
+  where it looks unnecessary.
+- **The token callback's own client must go straight to the sandbox.** A callback that
+  asks for a token through a client pointed at the session puts a request in front of
+  the waiting rule and an extra `http_request` in the log, which breaks every
+  assertion that counts requests exactly (`== 1` for RSC15l's 4xx test, `>= 2` for the
+  fallback ones). Build an inner `AblyRest(key=api_key, endpoint=SANDBOX_ENDPOINT)`,
+  request the token through that, and close it.
+- **`http_response` events carry no `path`.** They have `status` and `ruleMatched`
+  only, so "the injected response fired" is read off the response events **in order**
+  — `http_responses(log)[0]['status'] == 403` — rather than by filtering to an
+  endpoint. `http_request` events do carry `method` and `path`. A rule with no
+  `comment` appears as `ruleMatched: "rule-0"`.
+- **The parent package's timeout marker wins unless the subpackage prepends its
+  own.** `pytest-timeout` reads the first of an item's own markers, and
+  `rest/integration/conftest.py` marks everything beneath it with 120 seconds. The
+  proxy package's `pytest_collection_modifyitems` adds its 300 with
+  `append=False`; without that the marker order decides the timeout and a test that
+  waits out a twenty-second delay on a cold cache is cut off. Anyone adding a further
+  sub-tier under `test/uts/rest/integration/` hits this.
+- **A session-scoped async fixture runs on a different event loop from the tests.**
+  pytest-asyncio 0.23 gives the session fixture its own loop, so an object bound to
+  the loop that created it — an `httpx.AsyncClient`, say — must not be held across the
+  yield: reusing it from a test raises `RuntimeError: Event loop is closed` or attaches
+  to the wrong loop. `helpers/proxy.py` opens a client per control call for exactly
+  this reason, the way `sandbox.py` does.
+- **The session's `timeoutMs` is an idle timer, not a deadline.** The proxy's default
+  is 30000, measured from the last traffic through the session, and a test that has
+  the proxy delay a response by twenty seconds and then reads the log spends longer
+  than that idle, which is long enough for the session to be collected out from under
+  the test. The harness passes 120000.
+- **Every request the test's client makes lands in the same log.** The log is
+  per-session, not per-endpoint, so a verification step that reads history through the
+  same client adds its own `http_request` events. In `RSL1k4` the log is read
+  **before** the history call, and the history read is a `wall_clock_poll_until` rather
+  than a single fetch, because a published message does not reach history at once.
+- **`httpRequestTimeout` is milliseconds in the specification and seconds in
+  ably-python.** `ably/http/http.py:193` hands `(http_open_timeout,
+  http_request_timeout)` to `httpx`, which reads seconds, so the specification's
+  `http_request_timeout=3000` is a 3000-second deadline: measured, the request sat out
+  the proxy's whole 20-second delay and then succeeded on the primary host, and no
+  fallback was attempted. Passing `3` makes the same test pass in 3.1s, so only the
+  unit is wrong. The test is written as the specification has it and gated with
+  `@deviation`; `test/uts/deviations.md` carries the entry.
+
 ## Timers
 
 Three regimes; pick by tier.
@@ -617,8 +756,8 @@ silence against the same clock it arms its timer on. See the fake-time section o
 a server the tests exist to talk to, and shortening a timeout would only make the tier
 flaky. Poll with `wall_clock_poll_until` rather than sleeping a guess.
 
-The pytest timeout is 30 seconds for the suite and 120 for `rest/integration`, so keep
-waits well under whichever applies.
+The pytest timeout is 30 seconds for the suite, 120 for `rest/integration` and 300 for
+`rest/integration/proxy`, so keep waits well under whichever applies.
 
 ## Deviations
 
 
@@ -145,6 +145,54 @@ Tests here are given 120 seconds each, per `uts/docs/integration-testing.md`, ra
 than the 30 seconds `pyproject.toml` sets for the suite as a whole. The marker covers
 the integration package alone.
 
+`rest/integration/proxy/` routes its traffic through
+[ably/uts-proxy](https://github.com/ably/uts-proxy), a programmable proxy standing
+between the client and the sandbox. Those specifications are about what the SDK does
+when a request goes wrong — a connection dropped mid-request, a 503, a CloudFront 403,
+a response held past the request timeout — and the sandbox answers correctly, so the
+fault is injected in front of it. The proxy binds a port per session, takes plain HTTP
+on it and speaks TLS onwards to the sandbox, applies the rules the session was opened
+with, and records every request and response that crosses it.
+
+The binary is a pinned `uts-proxy` release. The first run that needs it fetches the
+release archive for the machine, checks it against the sha256 the release publishes,
+and extracts the binary into `~/.cache/uts-proxy/<version>/`, where every run
+afterwards finds it; the download is serialised on a lock file, so several Python
+versions starting at once on an empty cache fetch it once between them.
+`UTS_PROXY_LOCAL_PATH` names a locally built binary, or a `.tar.gz` holding one, to be
+used in place of the release, and `UTS_PROXY_CONTROL_URL` names a control API someone
+is already running, which the suite uses as it stands and leaves running. Otherwise one
+control process is started for the test session on a free port and reaped at the end of
+it; it serves every session the run opens.
+
+`proxy_session` is a specification's `create_proxy_session(...)`, and closes every
+session it hands out when the test ends. A client reaches its session by naming
+`localhost` and the session's port with TLS off, which disables fallback hosts (REC2c2);
+a scenario about a retry names the same session again as its fallback, so both attempts
+arrive at the one port and appear in the one event log, which `session.get_log()`
+returns:
+
+```python
+async def test_rsc15l_connection_drop_fallback(sandbox, proxy_session):
+    session = await proxy_session(rules=[{
+        'match': {'type': 'http_request', 'pathContains': '/time'},
+        'action': {'type': 'http_drop'},
+        'times': 1,
+    }])
+    client = sandbox_rest_client(
+        auth_callback=token_auth_callback(sandbox.key_str),
+        endpoint='localhost', fallback_hosts=['localhost'],
+        port=session.proxy_port, tls=False, use_binary_protocol=False)
+```
+
+A plain connection rules basic auth out, since RSC18 refuses it, so every client here
+authenticates through a callback whose own request goes straight to the sandbox and
+stays out of the event log.
+
+Tests in this package are given 300 seconds each: a cold cache downloads the binary
+before the first of them runs, and a specification that provokes a timeout sits through
+the delay it asked the proxy for.
+
 ## Running
 
 ```