Document the worker protocol in the example

Author: aherrmann

examples/persistent_worker/README.md

@@ -99,3 +99,41 @@ stderr for root//:demo-7 (demo):
 Bazel persistent worker ...
 ...
 ```
+
+## Protocol
+
+### Starlark
+
+A Buck2 persistent worker is created by a rule that emits the
+`WorkerInfo` provider. Setting `remote = True` on this provider
+indicates that this worker is remote execution capable.
+
+Buck2 actions indicate that they can utilize a persistent worker by
+setting the `exe` parameter to `ctx.actions.run` to
+`WorkerRunInfo(worker, exe)`, where `worker` is a `WorkerInfo` provider,
+and `exe` defines the fallback executable for non persistent-worker
+execution.
+
+Buck2 actions that want to utilize a remote persistent worker must pass
+command-line arguments in an argument file specified as `@argfile`,
+`-flagfile=argfile`, or `--flagfile=argfile` on the command-line.
+
+### Local Persistent Worker
+
+A locally executed Buck2 persistent worker falls under the [Buck2
+persistent worker protocol](./proto/buck2): It is started and managed by
+Buck2 and passed a file path in the `WORKER_SOCKET` environment variable
+where it should create a gRPC Unix domain socket to serve worker
+requests over. Multiple requests may be sent in parallel and expected to
+be served at the same time depending on the `concurrency` attribute of
+the `WorkerInfo` provider.
+
+### Remote Persistent Worker
+
+A remotely executed Buck2 persistent worker falls under the [Bazel
+persistent worker protocol](./proto/bazel): It is started and managed by
+the remote execution system. Work requests are sent as length prefixed
+protobuf objects to the standard input of the worker process. Work
+responses are expected as length prefixed protobuf objects on the
+standard output of the worker process. The worker process may not use
+standard output for anything else.