Telemetry: slices 4 + 2 — LastKnownPosition store + eviction, gRPC ReportLocations ingest

[erikshafer]

All four chunks complete — implementation (A–C) and docs/ledger (D), including the retro, which this repo's cadence ships in the session's own PR.

PR B of the W006 Telemetry transport chain, following #42 (skeleton + slice 1). Realizes slice 4 (LastKnownPosition store + heartbeat-absence eviction) and slice 2 (gRPC ReportLocations client-streaming ingest) together, because they are mutually dependent: slice 2's publish trigger evaluates against slice 4's document, and slice 4's document is written only when slice 2 decides to publish. Building either alone means evaluating against a document that does not exist, or writing one nothing reads.

This is the PR where CritterCab's showcase premise starts running. gRPC has been richly modeled across five workshops and sixteen ADRs and wired in zero lines of code. It now serves traffic.

What landed

Chunk A — version bump + proto codegen (aa31558)
All eleven WolverineFx* entries 6.19.0 → 6.21.0 in lockstep (bumping only WolverineFx + WolverineFx.Grpc would have left the other nine as a version island). 6.21.0 deliberately rather than the newer 6.22.0: it is the version the prompt's Verify-before-wiring citations were source-verified against, so the gate line numbers keep matching the binaries. Grpc.AspNetCore / Grpc.Tools / Google.Protobuf pinned to exactly what WolverineFx.Grpc 6.21.0 declares (2.76.0 / 2.76.0 / 3.31.1), so the codegen toolchain matches Wolverine's own tested pairing. First <Protobuf> item in the repo.

Chunk B — slice 4 (3222549, LastKnownPosition/)
LastKnownPosition is a plain Marten document defending no invariant — LWW on ServerReceivedAt is the entire concurrency story. It ships with a single timestamp: ServerReceivedAt serves both §6.2's lastPublishedAt trigger baseline and §6.4's eviction key, because §6.4 locks upsert-on-publish-only, which makes them the same instant by construction.

Eviction is split, because Wolverine has no first-class recurring-message primitive (ScheduleAsync is one-shot delayed delivery; ToLocalQueue() is routing config). The timer is a plain BackgroundService holding no logic; EvictStalePositionsHandler holds everything testable. It uses HardDeleteWhere rather than DeleteWhere — the latter silently degrades to a soft-delete flag if the document is ever configured for one, which would break the Return GWT.

Chunk C — slice 2 (ce34000, ReportLocations/)
TelemetryGrpcService is an empty abstract [WolverineGrpcService]. Two codegen layers stack: protoc emits the virtual ReportLocations over a raw IAsyncStreamReader, then Wolverine emits the override adapting it to IAsyncEnumerable and forwarding to IMessageBus.StreamAsync. The handler consequently never references a gRPC type — the whole stream is the message.

The per-ping pipeline lives inside the handler, which is forced rather than stylistic: Wolverine cannot weave Before/Validate frames for client-streaming, because a before-frame needs a concrete request at method entry and a stream cannot supply one. This is a deliberate, documented departure from slice 1's FluentValidation-at-the-boundary pattern — see GrpcServiceChain.cs:270-272.

Both fan-out targets are ready-to-swap seams: IDriverPrincipalAccessor (driverId from the principal, never the payload — R5, which is why the proto has no driver_id field) and IDriverLocationPublisher, carrying the generated DriverLocationUpdated so PR C swaps only the implementation, never the contract.

Firsts in code

• First gRPC surface that serves traffic, and the first client-streaming RPC — the WolverineFx.Grpc feature this project exists to showcase. Auto-generated, not hand-wired.
• First codegen behind a proto. protos/ files have been authored contracts with nothing consuming them since PR Telemetry v1 protobuf contracts (protos/crittercab/telemetry/v1) #39.
• First non-event-sourced document write path. Everything prior in CritterCab is event-sourced.
• First BackgroundService, and the first Wolverine message invocation from a test.
• First geospatial dependency (pocketken.H3).

The client-streaming forward-constraint is retired

Every prior handoff recorded that WolverineFx.Grpc could not auto-generate stream in → unary out and that ReportLocations would have to be hand-wired against IMessageBus. 6.21.0 shipped the emit path, and this PR consumes it. Nothing here is hand-wired. The stale comment in report_locations.proto and the two gRPC skills that still describe the workaround are corrected in chunk D.

Verification

• Gates 1–11 all closed. Gate 7 resolved by the bump itself (Marten 9.14 → 9.16.1, JasperFx 2.30.1, clean). Gate 8b closed against nuget.org — pocketken.H3 4.5.0.1 ships a native lib/net10.0 and pulls NetTopologySuite transitively, confirming the degrees-native Coordinate path costs no added dependency. Gate 11 dissolved: Alba wraps WebApplicationFactory over TestServer, so GetTestServer().CreateHandler() feeds a GrpcChannel directly — CritterCab keeps its Alba-first default with no parallel host recipe and no new test packages.
• 31/31 tests green locally, 16 of them new. Docker is working again (it was wedged throughout Telemetry: service skeleton + slice 1 (TelemetryPolicyConfigured config-as-events) #42), so Testcontainers ran locally rather than leaning on CI.
• The H3 pinning test proves order and units. It computes the same point down both API paths — Coordinate(lon, lat) in degrees and LatLng(lat, lon) in radians, mirror opposites on both axes, so they can only agree if production has both right — then separately asserts a swapped Coordinate yields a different cell. A swapped-axis bug produces a perfectly valid cell in the Indian Ocean, so "is a valid cell" would have shipped it.
• The DI guard was mutation-verified. IMessageBus is scoped and a BackgroundService is a singleton, so the eviction shell takes an IServiceScopeFactory. Temporarily injecting the bus directly was confirmed to fail host construction via CallSiteValidator — the regression test has real teeth.

Fixed in passing: apphost.cs did not compile

It has been broken since #42, which added the Telemetry service block without its #:project directive, so Projects.CritterCab_Telemetry never existed. CI only builds CritterCab.slnx and never the file-based apphost, so nothing caught it. Fixed here because the gRPC-endpoint deliverable cannot land on a file that does not build. gRPC needs no port of its own — it rides the existing HTTPS endpoint over HTTP/2, matching the convention the Dispatch block already documents. The CI gap is the more durable finding and is flagged for the retro.

Decisions taken during the session

Decision	Resolution
Version target	6.21.0, not 6.22.0 — keeps the verified gate citations matching the shipped binaries
LastKnownPosition shape	Minimal, one timestamp. LastPublishedAt collapsed into ServerReceivedAt; §3.3's DeviceTimestamp/Speed/Heading omitted (slice 3 passes them to Kafka straight from the ping)
lat/lon vs lng	Lon — the proto is the contract (ADR-009); §3.3's prose says lng
Publisher seam payload	The generated DriverLocationUpdated, so PR C swaps only the implementation
accuracyMeters threshold	Documented constant at 100m. W006 §6.2 names the threshold but fixes no value — this number is invented here, following §6.4's precedent for the 3×-heartbeat constant

Chunk D — docs and ledger (cf4ec73)

The stale proto comment mattered beyond tidiness. A .proto's leading comments become doc-comments in the generated C#, so the instruction to hand-wire against IMessageBus was being compiled into the build output. The replacement also records the middleware caveat at contract level, since it is a property of the RPC shape rather than of our implementation.

wolverine-grpc-handlers — corrected under the session-runner-blocking exception (a session cannot follow a skill telling it to hand-wire a shape the library now generates). Seven stale claims fixed, plus a new Client-streaming handlers section mirroring the server-streaming one. It documents three things this session had to learn from source rather than docs: middleware does not weave and fails silently rather than loudly; identity must come from an IHttpContextAccessor seam because there is no [WolverineBefore] to read ServerCallContext from; and the handler slot is keyed on the request type, so two client-streaming RPCs sharing one would collide.

wolverine-grpc-bidirectional-handlers — banner plus mental-model corrections only, as scoped. The ~145-line workaround body is left intact under an explicit obsolete banner rather than half-rewritten; its removal is a DEBT row. The mental-model table was corrected, because leaving "Rejected at startup" in the most-read section would have kept the file contradicting shipped code regardless of the banner.

Six DEBT rows, W006's Document History (including that MaxAccuracyMeters = 100 was invented at implementation time), both index entries, and the retro.

Resolved during chunk D

• Test class naming — registered as a DEBT row rather than fixed. The audit confirms testing-fundamentals is unambiguous and that all three Telemetry suites violate it, including Slice1TelemetryPolicyTests from Telemetry: service skeleton + slice 1 (TelemetryPolicyConfigured config-as-events) #42. That makes it rename-all-three or amend-the-skill; fixing only the two new ones would deepen the exact inconsistency the skill's own pitfall warns about.
• The three skill gaps — all registered, along with a fourth the audit surfaced: identity-acl's gRPC auth pattern depends on the same single-request binding client-streaming lacks, so it silently does not apply to streaming shapes and says nothing about it.

Known follow-up: CI cannot see the apphost

The apphost.cs break survived two weeks because CI builds CritterCab.slnx and never the file-based app. CI does have a "Verify solution completeness" step for exactly this class of mistake — but the apphost has no .csproj, so it falls through a guard already written to catch it. The fix is to extend that step, not to add a new one. Left for its own session; CI changes are their own scope.

Follow-on PRs

• C — slice 3 (DriverLocationUpdated → Kafka topic telemetry.driver-location-updated, partitioned by driverId). Swaps LoggingDriverLocationPublisher for the real producer, wires Kafka into apphost.cs, fires the topic-naming ADR candidate.
• D — slice 5 (Dispatch consumer: replaces NearbyAvailableDriversStub with the Kafka-fed view).