feat(kkrpc): add AsyncIterable streaming support

Server methods returning AsyncIterable are automatically detected and
streamed chunk-by-chunk to the client, where they're consumed via
for await...of. Supports consumer cancellation (break sends
stream-cancel), error propagation, concurrent streams, per-chunk
output validation, and interceptor integration.

Adds streaming-demo example, docs page, 9 integration tests.
Removes PLANNING.md — all roadmap items now complete.

Author: HuakunShen

.journal/2026-02-07.md

@@ -81,3 +81,50 @@ Also fixed a pre-existing inconsistency: `ioredis`, `kafkajs`, `socket.io`, and
 - **`pnpm-lock.yaml`** — will need `pnpm install` to reconcile the lockfile after this change
 - **CI** — adapter tests that import these packages will need them installed explicitly in the test environment (likely already the case via devDependencies or workspace config)
 - **Docs** — README adapter sections should note the required peer install (e.g., `npm install kkrpc kafkajs`)
+
+## 01:05 — AsyncIterable Streaming Support (PLANNING.md item 2)
+
+### Core Decision/Topic
+
+Implemented **streaming / subscription support** — the final major feature from the roadmap. Server methods can now return `AsyncIterable` (async generators), and kkrpc automatically streams chunks to the client where they're consumed via `for await...of`.
+
+### Options Considered
+
+- **Dedicated subscription API** (e.g. `channel.subscribe("topic")`) vs **transparent AsyncIterable detection** — chose transparent detection. If a handler returns something with `Symbol.asyncIterator`, kkrpc streams it automatically. No new API surface for users to learn; async generators "just work".
+- **Backpressure protocol** (consumer ACKs each chunk before producer sends next) vs **fire-and-forget chunks with buffering** — chose buffering. Simpler protocol, and most RPC streaming use cases (progress updates, log tailing, countdowns) don't need backpressure. Can be added later if needed.
+- **Per-chunk interceptor calls** vs **interceptors wrap initial handler only** — chose handler-only. Interceptors see the method call that starts the stream but don't fire per-chunk. This matches how middleware works in gRPC and tRPC.
+
+### Final Decision & Rationale
+
+**Protocol:** 4 new message types added to the wire format:
+- `stream-chunk` — producer → consumer, carries one value
+- `stream-end` — producer → consumer, signals completion
+- `stream-error` — producer → consumer, carries serialized error
+- `stream-cancel` — consumer → producer, signals `break` in `for await`
+
+The initial response carries `{ __stream: true }` to signal the consumer to create an AsyncIterable instead of resolving the Promise directly.
+
+**Consumer-side queue pattern:** Chunks arrive asynchronously; consumer reads synchronously via `next()`. Bridged with a buffer + waiters queue — chunks that arrive before `next()` are buffered; `next()` calls that arrive before a chunk park as pending resolvers.
+
+**Cancellation:** `break` in `for await` triggers the iterator's `return()` method, which sends `stream-cancel`. Producer uses `AbortController` to stop its iteration loop.
+
+**Validation integration:** Per-chunk output validation supported — if a schema is configured for the method's output, each chunk is validated before sending.
+
+### Key Changes Made
+
+| File | Change |
+|---|---|
+| `packages/kkrpc/src/serialization.ts` | Extended `Message.type` union with 4 streaming message types |
+| `packages/kkrpc/src/channel.ts` | Added ~200 lines: `StreamConsumerState`/`StreamProducerState` interfaces, `isAsyncIterable()` helper, stream routing in `processDecodedMessage`, producer methods (`streamResult`, `sendStreamError`, `handleStreamCancel`), consumer methods (`createStreamIterable`, `handleStreamChunk`, `handleStreamEnd`, `handleStreamError`), cleanup in `destroy()` |
+| `packages/kkrpc/__tests__/streaming.test.ts` | 9 integration tests over real WebSocket: basic countdown, coexistence with regular methods, error propagation, consumer cancellation, concurrent streams, interceptor interaction, delayed chunks, empty stream, nested method streaming |
+| `packages/kkrpc/README.md` | Added streaming section with code examples and comparison table row |
+| `docs/src/content/docs/guides/streaming.md` | Standalone docs page covering usage, cancellation, errors, concurrency, protocol details |
+| `examples/streaming-demo/` | Full working example: `api.ts` (3 streaming methods + 1 regular), `server.ts` (WebSocket + logging interceptor), `client.ts` (5 demo patterns), `README.md` |
+| `PLANNING.md` | Removed — all planned features now implemented |
+
+### Future Considerations
+
+- **Backpressure** — for high-throughput streaming (e.g. file transfer), a flow-control protocol (consumer ACKs) would prevent memory buildup
+- **Bidirectional streaming** — current design is server→client only. Client→server streaming would need a `sendStream()` API on the proxy
+- **Stream timeout** — currently streams can run indefinitely. A per-stream idle timeout could auto-cancel stalled streams
+- **PLANNING.md removed** — all 4 major roadmap items (middleware, streaming, timeout, type safety) are complete