PR-B1 (ADR 0008 Phase B): gRPC server stub — Create / Close / GetSessionInfo

[FluffyAIcode]

What

First PR of ADR 0008 Phase B. Lands the gRPC RuntimeService
surface implementing three of the five §2.2 RPCs against the
SessionStore from PR-A2 / PR-A3b:

service RuntimeService {
  rpc CreateSession  (CreateSessionRequest)  returns (CreateSessionResponse);   // ✅ PR-B1
  rpc AppendTokens   (AppendTokensRequest)   returns (AppendTokensResponse);    // PR-B2
  rpc Generate       (GenerateRequest)       returns (stream GenerateResponse); // PR-B3
  rpc CloseSession   (CloseSessionRequest)   returns (CloseSessionResponse);    // ✅ PR-B1
  rpc GetSessionInfo (GetSessionInfoRequest) returns (GetSessionInfoResponse);  // ✅ PR-B1
}

AppendTokens and Generate return UNIMPLEMENTED (gRPC
framework default for non-overridden servicer methods, correct per
§2.10 "no graceful degradation"). Two regression tests prevent a
future PR-B2 / PR-B3 from forgetting to implement them.

✅ Mac M4 review evidence — landed (commit 097ca0b)

Artifact	Path	Result
pytest report	results/platform-tests/pr-b1-mac-grpc-tests-1780317235.json	22 / 22 passed, 0 failures, 0 errors, 0 skipped
pytest junit	results/platform-tests/pr-b1-mac-grpc-tests-1780317235.junit.xml	per-case timings + outcomes
pytest coverage	results/platform-tests/pr-b1-mac-grpc-tests-1780317235.coverage.xml	100.00 % on inference_engine/server/grpc_app.py (46 / 46 lines)
smoke report	results/platform-tests/pr-b1-mac-grpc-smoke-1780317235.json	10 / 10 passed, every step's observed code matches expected

host:  macOS-26.5-arm64-arm-64bit-Mach-O / arm64 / Python 3.13.12 / grpcio 1.81.0

Per-step smoke results on Mac M4:

#	Step	Expected	Observed	Time
1	CreateSession	ok	ok	1.06ms
2	GetSessionInfo (initial)	ok	ok	0.37ms
3	CloseSession	ok	ok	0.47ms
4	CloseSession (double-close)	NOT_FOUND	NOT_FOUND	0.47ms
5	GetSessionInfo (after close)	NOT_FOUND	NOT_FOUND	0.39ms
6	AppendTokens (PR-B2)	UNIMPLEMENTED	UNIMPLEMENTED	0.53ms
7	Generate (PR-B3)	UNIMPLEMENTED	UNIMPLEMENTED	0.40ms
8	CreateSession (eos + client_label)	ok	ok	0.35ms
9	CreateSession (pool slab #1 / 1)	ok	ok	0.73ms
10	CreateSession (pool exhausted)	RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED	0.42ms

Each scenario maps 1-to-1 to an ADR 0008 contract clause (§2.2 / §2.6 / §2.9 / §2.10). The gRPC surface behaves identically on Linux CI (Python 3.12.13 / x86_64) and on the reviewer's Mac M4 (Python 3.13.12 / arm64).

Reviewer-script hotfix (commit 79a82f2)

The reviewer reported that scripts/review_pr_b1_on_mac.sh segfaulted on Python 3.13 inside pytest-cov's tracer initialization (conftest-import time race with torch._C). They worked around it manually using coverage run -m pytest and produced the same artifacts.

Folded that workaround into the script in commit 79a82f2 so future reviewers don't have to discover it. The fix is functionally identical to the pytest-cov path (same coverage data, same XML / term reports, same --fail-under=100 enforcement) — it just initializes coverage tracing before pytest loads, sidestepping the torch / coverage race. No code under test changed; the Mac M4 evidence in 097ca0b stands.

Architecture (unchanged)

• asyncio (grpc.aio) per ADR 0008 §2.5
• Loopback by default per §8 OQ-5 (127.0.0.1:50051)
• Error mapping per §2.6 / §2.10:

  SessionStoreError	gRPC status	Reachable in PR-B1?
  SessionNotFoundError	NOT_FOUND	✅ tested via Close + GetSessionInfo
  PoolExhausted	RESOURCE_EXHAUSTED	✅ tested via Create with capacity > num_slabs
  InvariantViolation / ValueError	FAILED_PRECONDITION / INVALID_ARGUMENT	❌ not wired — PR-B2 territory when AppendTokens triggers them

Files

Status	Path	Notes
add	inference_engine/server/grpc_app.py (215 lines)	RuntimeServiceServicer + GrpcServerConfig + factory
add	inference_engine/server/proto_gen/... (502 lines)	Generated stubs; CI's proto-stub-drift gate
add	scripts/regenerate_proto_stubs.sh	Canonical regeneration command
add	scripts/smoke_grpc_runtime.py	Reviewer aid: 10-scenario smoke
add	scripts/review_pr_b1_on_mac.sh	One-shot Mac M4 reviewer runner
add	tests/inference_engine/server/test_grpc_app.py (22 tests)	Real grpc.aio server + client
add	results/platform-tests/pr-b1-mac-grpc-{tests,smoke}-1780317235.{json,junit.xml,coverage.xml}	Mac M4 evidence
mod	requirements.txt	+ grpcio>=1.65,<2.0, + grpcio-tools>=1.65,<2.0
mod	.coveragerc	omit += inference_engine/server/proto_gen/*
mod	.github/workflows/ci.yaml	+ proto-stub-drift job; smoke imports

Linux CI status (main workflow on this PR)

unit tests + 100% coverage (3.12)  pass    562 passed, 100.00 % on 1382 stmts
package import smoke               pass
proto lint (buf)                   pass    8s
proto stub drift                   pass    35s   (regen → git diff --exit-code)
docker build + import smoke        pass

Per ADR 0008 §9

Linux-only-path carve-out invoked: zero MLX runtime code; the
gRPC server / SessionStore / generated stubs are platform-neutral
pure Python. Mac M4 evidence above is a review affordance, not
a §9 requirement — but the reviewer chose to run on hardware
anyway, which is strictly stronger than the carve-out demands.

The first PR of Phase B that does trigger §9's mandatory Mac
M4 report is PR-B3 (Generate server-streaming with the
verifier sampler on real MLX).

Reviewer checklist

• Mac M4 evidence on branch: 22/22 pytest, 100% coverage on grpc_app.py, 10/10 smoke. Pushed in commit 097ca0b.
• Reviewer-script segfault hotfix: replaced pytest-cov path with coverage run -m pytest. Pushed in commit 79a82f2.
• Generated stubs are reproducible: CI's proto-stub-drift job confirms on every push.
• Loopback default preserved (DEFAULT_BIND_ADDRESS == "127.0.0.1:50051").
• UNIMPLEMENTED regression tests prevent silent regression of PR-B2 / PR-B3.
• No new MLX runtime paths.
• PooledVerifier / inference_engine.memory/ untouched.
• Error mapping is honest: only the reachable subset is wired and tested.

Next PR

PR-B2: implement AppendTokens + the §2.3 byte-exact prefill-incremental contract. Wires InvariantViolation → FAILED_PRECONDITION and ValueError → INVALID_ARGUMENT. Adds INV-3 determinism unit tests on the internal code path. Linux-only path until PR-B3's Generate touches MLX.