1 files changed, 60 insertions, 0 deletions
diff --git a/research/experiments/005-direct-document-peer/README.md b/research/experiments/005-direct-document-peer/README.md
new file mode 100644
index 0000000..d35ba20
--- /dev/null
+++ b/research/experiments/005-direct-document-peer/README.md
@@ -0,0 +1,60 @@
+# Authenticated document peer: direct versus Pure
+
+This experiment uses the real `editor.pure` document app over the same TLS
+1.3/TCP transport and `pure-doc/1` wire format. `direct-peer.c` is a
+research-only server that parses the same authored program and calls the same
+store and evaluator directly. `pure-document-server` is the selected product
+server build without its native client commands. The baseline is limited to
+the tested synchronous document workflow: it has no Pure work tickets,
+admission/lifetime contract, cross-domain forwarding, or cancellation.
+
+Both servers passed the existing `check_document_peer.py` suite: mutual TLS
+identity, ALPN, source identity, external Python and native C clients, version
+conflicts, one-byte replacement of a 1 MiB value, fragmented/invalid/truncated
+frames, deadlines, and restart. The direct and Pure server builds passed the
+same suite under ASan/UBSan. These checks do not establish full feature or
+security equivalence under concurrent clients or failure networks.
+
+To run the selected product checks on Linux AArch64:
+
+```sh
+make -C prototypes/connections check-document-peer
+make -C prototypes/connections check-document-server
+```
+
+The first command checks the existing combined client/server executable; the
+second checks the server-only code ceiling and runs the same peer scenarios
+with the native C client from the combined executable. Both need permission
+to bind a local TCP port. The server-only executable and budget are optional;
+the default core and CLI do not link TLS.
+
+To reproduce the read comparison:
+
+```sh
+python3 research/experiments/005-direct-document-peer/run.py \
+  --body-bytes 8192 --reads 1024 --pairs 6 \
+  --output research/experiments/005-direct-document-peer/results/local-8k.json
+python3 research/experiments/005-direct-document-peer/run.py \
+  --body-bytes 1048576 --reads 64 --pairs 4 \
+  --output research/experiments/005-direct-document-peer/results/local-1m.json
+```
+
+The runner compiles both servers from source. Each trial creates and reads a
+real stored document, then times repeated full reads on one authenticated,
+persistent Python TLS connection. It verifies every response and the final
+stored file hash. TLS handshake, certificate creation, file creation, and the
+first cache-warming read are outside the timed batch. The server process RSS
+is recorded before and after. Fresh stores and alternating order reduce some
+order effects but do not control CPU frequency, OpenSSL or Python overhead,
+network behavior beyond local loopback, or host scheduling. The JSON files
+contain all individual samples, source hashes, compiler and OpenSSL versions.
+
+The short `before-nodelay` and `after-nodelay` artifacts repeat exactly 32
+authenticated 8 KiB reads through each server, differing only in the common
+TLS transport's TCP_NODELAY option. This intervention supports a Nagle/delayed
+ACK explanation for the prior ~44 ms per-request stall; no packet trace was
+captured, so that exact kernel interaction remains an inference. The longer
+post-change runs are for direct-versus-Pure cost, not a claim of Internet or
+Kitex/QUIC performance.
+
+See [the result report](../../../docs/research/055-authenticated-peer-transport-cost.md).