# Add realtime checkpoint path for OpenAPI GetChangefeed

**Date**: 2026-06-18
**PR**: N/A
**Module**: `app/controllers/open/changefeed`
**Domain**: `CDC`

---

## Background

OpenAPI `GetChangefeed` has already exposed `invalidate_cache`, but the current implementation always returns checkpoint information from cached connector data. That cache is refreshed by the periodic worker, so checkpoint can lag behind the latest kernel state.

This change introduces an opt-in realtime path for `GetChangefeed`: when `invalidate_cache=true`, fetch the latest kernel detail through the existing connector detail RPC and override checkpoint fields before returning the response.

---

## Analysis

### Impact Table

| Area | File | Change | Verification | Success Criteria |
|------|------|--------|--------------|------------------|
| OpenAPI adapter | `app/controllers/open/changefeed/adapter_model.go` | Add realtime checkpoint refresh and robust parsing for `checkpointTso` from detail payload | `go test ./app/controllers/open/changefeed -run TestAdapterGetChangefeed_InvalidateCache -count=1` | New test passes and returned checkpoint follows realtime payload |
| Connector API contract | `app/controllers/open/changefeed/service.go` | Extend `ConnectorServiceServer` with `GetChangefeedDetail` | `go test ./app/controllers/open/changefeed -run TestGetChangefeed -count=1` | Existing `GetChangefeed` service tests pass |
| Unit tests | `app/controllers/open/changefeed/service_test.go` | Add adapter tests for invalidate-cache enabled/disabled/error paths; extend stub method set | `go test ./app/controllers/open/changefeed -count=1` | Package tests pass |

### Dead Code Cascade

No dead code removal is expected. This is an additive behavior change behind request flag `invalidate_cache`.

### Symbols To Keep / Introduce / Remove

- **Keep**: `connectorChangefeedAdapter.GetChangefeed`, `ConnectorServiceServer.GetConnector`
- **Introduce**: `ConnectorServiceServer.GetChangefeedDetail`, `refreshRealtimeCheckpoint`, `parseCheckpointTSOFromChangefeedDetail`
- **Remove**: None

---

## Execution Steps

1. Extend open changefeed connector interface to support detail retrieval.
   - Verification: `go test ./app/controllers/open/changefeed -run TestGetChangefeed -count=1`
   - Success criteria: compile and existing service-level GetChangefeed tests pass.

2. Implement realtime checkpoint refresh in adapter path when `invalidate_cache=true`.
   - Verification: `go test ./app/controllers/open/changefeed -run TestAdapterGetChangefeed_InvalidateCache -count=1`
   - Success criteria: checkpoint in response equals realtime detail checkpoint and cache-bypass path is exercised.

3. Validate whole package behavior.
   - Verification: `go test ./app/controllers/open/changefeed -count=1`
   - Success criteria: all tests pass with no regression in existing open changefeed APIs.

---

## Risk Assessment

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Realtime detail payload checkpoint field type differs (string/number) | Medium | Medium | Parse both string and number forms with explicit validation |
| New dependency on detail RPC adds extra call latency | Medium | Low | Only enable when caller sets `invalidate_cache=true` |
| Missing checkpoint field in detail response | Low | Medium | Return explicit error instead of silently falling back |