Telemetry v1 protobuf contracts (protos/crittercab/telemetry/v1)

[erikshafer]

Realizes Workshop 006 §10's owed Telemetry proto surface (design-locked R1–R8, ADR-018). Item 2 of the post-tidy-38 handoff. Transcription of a locked design into wire contracts — no re-grilling, no C#.

First gRPC client-streaming surface and first Kafka-event proto in CritterCab.

Deliverables

• protos/crittercab/telemetry/v1/report_locations.proto — TelemetryService.ReportLocations(stream LocationPing) → LocationIngestAck (client-streaming ingest, W006 §6.2).
• protos/crittercab/telemetry/v1/driver_location_updated.proto — DriverLocationUpdated Kafka event, message-only (W006 §6.3; ADR-018 supplier half). Mirrors ride_assigned.proto's header-comment shape.
• protos/buf.yaml — the repo's first scoped ignore_only lint exception.
• Prompt + retro under docs/{prompts,retrospectives}/decisions/003-protobuf-telemetry-v1.md; index entries; W006 ## Document History records the §10 realization (spec-delta closure loop).

Decisions (user sign-off 2026-07-04)

Four durable wire/config forks were put to the user (details in the prompt):

1. RPC naming — keep the ubiquitous-language names LocationPing / LocationIngestAck via a file-scoped buf.yaml ignore_only for RPC_REQUEST_STANDARD_NAME + RPC_RESPONSE_STANDARD_NAME, rather than renaming to ...Request/...Response. Service conforms as TelemetryService. Every other proto stays fully STANDARD.
2. Coordinates — flat lat/lon scalars (workshop's flat shape; lon matches common.v1.Location; no vestigial street_address on a ping).
3. throttle_policy_version — int64 (verified numeric Marten stream version, long).
4. buf codegen — deferred to the implementation session (no CritterCab.Telemetry.csproj yet; buf.gen.yaml already configured — PR Add Dispatch business-event protobuf contracts #4 precedent).

Forward-constraint for the implementation session (not a design change)

jasperfx-source-verifier confirmed WolverineFx.Grpc has no client-streaming auto-codegen adapter on the verified 5.x line — a [WolverineGrpcService]-marked stub declaring this RPC fails fast at startup (NotSupportedException). The .proto itself is plain proto3 (Wolverine imposes no proto-side shape), so the locked R5 client-streaming contract stands. The implementation session must hand-wire ReportLocations against IMessageBus, or re-verify 6.8's adapter support first (the local checkout was pre-6.0 and could not confirm 6.8).

Proto Change Classification

• No proto changes
• Non-breaking proto changes — list:
  • Added new package crittercab.telemetry.v1 with two files (report_locations.proto, driver_location_updated.proto). Net-new — no existing message, field, service, or RPC modified.
  • buf.yaml: added a file-scoped lint.ignore_only for two RPC-name rules (config-only; no wire impact).
• Breaking proto changes

Verified locally via the npm-distributed @bufbuild/buf: buf lint, buf format, and buf breaking --against main all pass. (The ignore_only exception is load-bearing — lint fails without it.)

Notes

• Surfaced two protobuf-contracts skill gaps (stale single-file directory diagram; a streaming example that would itself fail the repo's STANDARD gate) — registered in the retro for a future tidy: skills session, not fixed here (no opportunistic edits).
• Observed the docs/prompts/README.md Decisions index was already missing its 002-bundled-pattern-adrs entry (pre-existing) — left as-is; flagging for housekeeping.