feat(api): add bounded gRPC operational adapter

[ryan-wong-coder]

Linked Issue

Fixes #11

Summary

• add a reusable grpc-go 1.82.1 operational adapter that registers only the standard grpc.health.v1.Health service
• share the atomic readiness tracker with HTTP, start fail-closed, refresh Check/List/Watch safely, and publish NOT_SERVING before drain
• enforce bounded message, application metadata, per-connection transport-header, concurrent-stream, keepalive, connection-lifetime, and unary-work limits
• add safe request IDs, allowlisted synchronous access logs, panic isolation, root cancellation, and a single-use GracefulStop-to-Stop lifecycle
• document the exact bootstrap boundary: no listener wiring, reflection, custom protobuf, business RPC, consensus API, or runnable node service

Required Format

• Branch name uses an approved prefix: feat/, fix/, docs/, test/, refactor/, perf/, security/, chore/, ci/, build/, release/, or revert/.
• PR title uses Conventional Commit style, for example fix(consensus): reject equivocated proposer slots.
• Commit messages use Conventional Commits.

Scope And Project Status

• This PR solves one issue or one clearly scoped maintenance task.
• This PR excludes unrelated formatting, experiments, generated files, local data, credentials, logs, captures, and build artifacts.
• User-facing material distinguishes implemented behavior, target design, and roadmap work.
• Any performance claim identifies its source, hardware, configuration, measurement method, and whether it is a FinalWeave result.

No performance claim is introduced.

Protocol, Safety, And Compatibility

• This PR does not change quorum, Byzantine fault, proposer-slot, stable-prefix, or epoch-transition rules.
• BatchAC still proves recoverable data availability only; it is not treated as transaction validity, ordering, or execution finality.
• Canonical ordering and speculative parallel execution remain deterministic and equivalent to canonical serial Apply.
• External finality remains bound to an authenticated Header, exact FinalityCertificate, locally trusted validator/config chain, and query-specific proofs.
• This PR does not change canonical encoding, domain separation, signatures, IDs, state commitments, or FinalWeave wire schemas.
• WAL, atomic publication, snapshots, pruning, synchronization, replay, and recovery preserve their durable safety boundaries.
• This PR does not change networking, admission, cross-ledger proof validation, or resource-accounting boundaries.
• No production path introduces unbounded scan, sort, load, verification, retry, amplification, or recomputation behavior.

The unchecked boundary is intentional: this PR introduces the local operational gRPC transport and its resource accounting. It is isolated from consensus and persistence, registers only the standard gRPC Health schema, and opens no listener. Message sizes, application metadata, transport headers, concurrent streams, their per-connection products, connection age/idle, keepalive, unary work, request IDs, and shutdown are bounded and validated without silent clamping. A future composition root must separately bound process-wide listener connections when it wires an active transport. There are no releases or runtime users, so no migration or compatibility layer is required. Rollback is a clean revert of this adapter and the grpc-go dependency.

Validation

• git diff --check
• python3 scripts/check_docs.py
• go mod verify and a clean go mod tidy diff
• go vet ./...
• go test -count=1 -mod=readonly ./...
• go test -race -count=1 -mod=readonly ./...
• python3 scripts/check_go_architecture.py
• Relevant unit, race, property, fuzz, vector, model, Byzantine, partition, crash-recovery, snapshot, chaos, and performance checks
• Negative tests cover malformed, conflicting, stale, replayed, oversized, and partially durable inputs where applicable

Additional focused validation:

• go test -count=20 ./pkg/api/grpcserver
• go test -race -count=20 ./pkg/api/grpcserver
• lifecycle race/forced-stop/shared-drain stress tests with -race -count=100
• real TCP and bufconn tests for Health, Watch, message/metadata limits, stream saturation, request IDs, panic recovery, graceful drain, forced Stop, and startup/shutdown races
• secret-disclosure negative tests for payloads, metadata, request IDs, and panic values
• Linux amd64 and arm64 static builds with -trimpath

Protocol property, vector, model, Byzantine, partition, crash-recovery, snapshot, and chaos suites are not applicable because this PR adds no consensus, storage, canonical encoding, custom wire schema, or active runtime. Residual operational risk is limited to future listener/TLS/composition-root integration, which remains explicitly absent and must receive its own issue and tests.

Risk And Rollback

The main risks are transport lifecycle races, inaccurate resource ceilings, readiness becoming SERVING too early, and sensitive metadata entering logs. The implementation starts NOT_SERVING, uses the existing atomic tracker, freezes a single-use lifecycle, makes concurrent shutdown callers share the initiating drain result, forces Stop on deadline, counts repeated HTTP/2 metadata fields, and logs only fixed allowlisted fields. Unit, integration, stress, and race tests cover these boundaries.

Rollback by reverting this commit. No persisted data, protocol state, generated code, migration, listener, or compatibility shim must be removed.