docs(das-client): record real gRPC/bus-node/handle progress and the precise live-DAS boundary

Author: MesTTo

packages/das-client/README.md

@@ -2,22 +2,23 @@
 
 Distributed AtomSpace (DAS) as a pluggable `Space` backend for MeTTa TS.
 
-## What ships here
+## What ships here (real, tested)
 
-- **`DasTransport`** — the network boundary interface (`query`/`add`/`remove`/`atoms`).
-- **`DasSpace`** — implements the kernel's `Space` interface over a transport, so a DAS is just another Space backend (drops in wherever `InMemorySpace` does). Mock-tested.
-- **`MockTransport`** — an in-process transport that exercises the exact `DasSpace` code paths, for tests and offline development.
-- **`das.metta`** — the vendored DAS module type declarations (`new-das!`, `das-evolution!`, `das-link-creation!`, …) from hyperon-experimental.
+- **gRPC stubs** generated from `singnet/das-proto` (`src/gen/`): `DistributedAlgorithmNode` (`ping`, `execute_message`), `attention_broker`, `MessageData{command, args, sender, …}`. Regenerate with `pnpm --filter @metta-ts/das-client gen` (needs `protoc`).
+- **`BusNode`** — a real DAS bus node over those stubs: hosts an inbound gRPC server and sends `execute_message` to peers. Verified end-to-end in-process (two nodes exchange a `ping` and a `bus_command_proxy` command over the wire — no live DAS needed for that test).
+- **Atom-handle hashing** (`handle.ts`) — a faithful port of `hyperon_das/hasher.py`, validated against independent **MD5 parity vectors** (a wrong handle makes every query miss, so this is the load-bearing piece).
+- **`DasTransport` / `DasSpace`** — the Space-backend abstraction: `DasSpace` implements the kernel's `Space` interface over a transport, so a DAS drops in wherever `InMemorySpace` does. Mock-tested.
+- **`MockTransport`** — an in-process transport exercising the exact `DasSpace` paths.
+- **`das.metta`** — the vendored DAS module type declarations (`new-das!`, `das-evolution!`, …).
+- The bus command vocabulary (`BusCommand`) read from the Python `service_bus`.
 
-## What does not ship (the remaining integration)
+## The one remaining boundary (needs a live DAS to validate)
 
-The **live bus client** is deliberately not shipped as unverified code. DAS's distributed layer is gRPC (`singnet/das-proto`: `DistributedAlgorithmNode.execute_message`, `attention_broker`) plus a peer-to-peer streaming choreography. Completing it means:
+What's left is the **streaming pattern-matching choreography**: the proxy joins the network, issues a `PATTERN_MATCHING_QUERY` over `bus_command_proxy`, and assembles the streamed `query_answer_tokens_flow` — specifically the `ANSWER_BUNDLE`/`COUNT` token decoding into `QueryAnswer` bindings (`hyperon_das/service_clients/pattern_matching_query.py`).
 
-1. Generate gRPC stubs from `das-proto` (ts-proto + `@grpc/grpc-js`).
-2. Port the choreography from the Python reference `hyperon_das` (~2.8k LOC): service bus, proxy, port pool, distributed-algorithm bus node, pattern-matching + atomdb clients, and atom-handle hashing (capture parity vectors from the Python client first).
-3. Validate against a live DAS (`das-toolbox`) in an integration test.
+This is intentionally **not** shipped as an unverified best-guess. Its exact wire format (token framing, answer encoding) can only be validated byte-for-byte against a running DAS (`das-toolbox`) or recorded real traffic — porting it blind would violate the project's correctness-first rule (don't ship sound-but-unverified code as if it works). The pieces it composes (gRPC transport, bus node, handle hashing, command vocabulary) are all real and tested above; finishing it is: stand up a DAS, capture/observe the answer-token frames, port the decoder, add the live differential test.
 
-This is **Node-only**: a participant must host an inbound bus node, which a browser cannot do — the browser reaches DAS through [`@metta-ts/das-gateway`](../das-gateway). Per the project's correctness-first principle, this lands behind a live-DAS differential test rather than as untested wire-protocol code.
+**Node-only:** a participant hosts an inbound bus node, which a browser cannot do — the browser reaches DAS through [`@metta-ts/das-gateway`](../das-gateway).
 
 ## Kernel integration note