PR-B2 (ADR 0008 Phase B): AppendTokens + byte-exact prefill-incremental contract

[FluffyAIcode]

⚠️ Stacked PR

Depends on PR #44 (PR-B1). Diff against main shows both PRs;
once #44 merges, this auto-rebases to a clean PR-B2-only diff.

✅ Mac M4 review evidence — landed (commit 7c132dc)

Artifact	Result
pr-b2-mac-coordinator-tests-1780320664.json	19 / 19 passed, 100.00 % on inference_engine/session/coordinator.py (32 / 32 lines)
pr-b2-mac-grpc-tests-1780320664.json	28 / 28 passed, 100.00 % on inference_engine/server/grpc_app.py (59 / 59 lines)
pr-b2-mac-grpc-runtime-smoke-1780320664.json	10 / 10 passed (PR-B1 regression: AppendTokens stays UNIMPLEMENTED w/o coordinator)
pr-b2-mac-grpc-appender-smoke-1780320664.json	10 / 10 passed including INV-1 → FAILED_PRECONDITION
Host	macOS-26.5-arm64-arm-64bit-Mach-O / arm64 / Python 3.13.12 / grpcio 1.81.0

Reviewer-script hotfixes (two commits)

Two issues surfaced during the Mac M4 run, each with a fix folded back
into the script so future reviewers don't repeat the workaround:

1. 9cb1c56 — segfault from COVERAGE_CORE=sysmon + --source

COVERAGE_CORE=sysmon (env var) initialized the sys.monitoring
backend earlier than coverage's own startup, racing with torch's _C
extension on Python 3.13.12 and segfaulting. --source=<module> on
coverage run reproduced the same race via a different path.

Fix: drop the env var (.coveragerc already sets core = sysmon,
which is the safe deferred-init path); drop --source; apply
--include=<path> at report time instead.

2. 9d1a250 — junit.tests: 0 in the JSON summary

pytest's --junitxml writes a <testsuites> root wrapping a
<testsuite> child; the count attributes (tests, failures,
errors, skipped) live on the inner element. The previous
helper read them off the root → silently produced 0s. The user
worked around it by hand-correcting the JSONs to the actual counts
(coordinator 19, gRPC 28).

Fix: aggregate counts from every <testsuite> element under the
root, so the helper is correct whether the producer emits the
<testsuites> wrapper (pytest) or just <testsuite> (other
producers). Verified locally against the user's existing JUnit XMLs:
the new helper produces exactly the hand-corrected numbers (19, 28).

Three deliverables (unchanged)

1. inference_engine/session/coordinator.py (new)

Symbol	Role
VerifierProtocol	Subset of the verifier API the coordinator needs. Both CPU SinkWindowVerifier and MLX MLXSinkWindowVerifier satisfy structurally.
AppendTokensCoordinator(store, verifier)	The §2.3 byte-exact dispatch orchestrator.

if session.next_global_position == 0:
    verifier.prefill(token_list)                    # cold start
else:
    block_logits = verifier.forward_block(token_list)
    verifier.commit_or_truncate(forwarded=L, accepted=L)
    verifier.next_token_logits = block_logits[-1].clone()

session.cached_token_sequence = list(verifier.cached_token_sequence)
store.append_tokens(session_id, token_list)         # extends history + INV-1
store.record_position_advance(session_id, verifier.next_global_position)  # INV-2

2. RuntimeServiceServicer.AppendTokens (new)

Path	gRPC status
Servicer constructed without coordinator (PR-B1 mode)	UNIMPLEMENTED
SessionNotFoundError	NOT_FOUND
ValueError	INVALID_ARGUMENT
InvariantViolation	FAILED_PRECONDITION
Success	AppendTokensResponse(history_length=...)

Generate stays UNIMPLEMENTED (PR-B3).

3. INV-3 byte-exact unit tests via FakeVerifier

TestInv3ByteExactDispatch drives the same 30-token sequence through
three different chunkings (1×30, 4×medium, 15×2) and asserts
byte-identical final (cached_token_sequence, next_global_position, next_token_logits). The FakeVerifier mirrors the real
SinkWindowVerifier's mutation contract (sink+window trim in
commit_or_truncate, parallel-sequence growth in forward_block)
without loading model weights — Linux-runnable in <50 ms.

Linux CI

unit tests + 100% coverage (3.12)  pass    587 passed, 100.00% on 1428 stmts
package import smoke               pass
proto lint (buf)                   pass
proto stub drift                   pass
docker build + import smoke        in flight (typical 8-9 min on this PR)

Per ADR 0008 §9

Linux-only-path carve-out: zero MLX runtime code in this PR. The Mac
M4 evidence above is a review affordance, strictly stronger than §9
demands. The first PR with mandatory §9 Mac M4 report is still
PR-B3 (Generate server-streaming with verifier sampler on real
MLX).

Reviewer checklist

• §2.3 byte-exact contract: TestInv3ByteExactDispatch passes for 3 chunkings (Linux + Mac M4).
• Dispatch logic: first call → prefill; subsequent → forward_block + commit_or_truncate(forwarded=L, accepted=L). Verified by FakeVerifier.call_log.
• State mirroring: session.cached_token_sequence == verifier.cached_token_sequence and session.next_global_position == verifier.next_global_position after every append.
• 3 new error mappings tested (NOT_FOUND, INVALID_ARGUMENT, FAILED_PRECONDITION). INVALID_ARGUMENT is exercised through a coordinator-subclass test because uint32 blocks negative ints at the wire layer.
• PR-B1 regression preserved: test_append_tokens_returns_unimplemented_when_no_coordinator keeps the no-coordinator path at UNIMPLEMENTED.
• Empty token list is no-op: test_empty_token_list_is_noop + sibling.
• No new MLX runtime paths (git diff main inference_engine/backends/).
• PooledVerifier / inference_engine.memory/ untouched.
• Reviewer scripts robust: segfault path removed; JSON tests field aggregated correctly. Both 9cb1c56 and 9d1a250 verified end-to-end on the same Linux dev VM that previously reproduced both bugs.

Next PR

PR-B3: implement Generate server-streaming RPC. First Phase B
PR that exercises real MLX runtime paths; mandatory Mac M4 §9 report
on the PR branch before merge.