Split from https://gitlab.com/gitlab-org/gitlab/-/work_items/612586, found while investigating https://gitlab.com/gitlab-org/gitlab/-/work_items/612557. ### Background Duo Workflow's incremental-checkpoint read path (epic https://gitlab.com/groups/gitlab-org/-/work_items/22939) is meant to progressively move every checkpoint reader off the legacy full-row `p_duo_workflows_checkpoints` table and onto `checkpoint_headers` + `checkpoint_blobs`, reconstructing `channel_values` on read. `trace.jsonl` and the GraphQL `checkpoint`/`duoMessages` fields are already migrated this way; https://gitlab.com/gitlab-org/gitlab/-/work_items/612586 covers the GraphQL `latestCheckpoint`/`firstCheckpoint` fields, the dominant resume source. ### Problem The internal `checkpoints` list/get REST endpoints (`ee/lib/api/ai/duo_workflows/workflows_internal.rb:141-243`) still read the legacy `checkpoints` table unconditionally, with no `checkpoint_headers` fallback. The Duo Workflow Service depends on them for: - the STOP_RECOVERY boundary walk (`checkpoints_reversed()` in `gitlab_workflow.py:1414`, called from `Flow._resolve_stop_recovery()`) - LangGraph time-travel/replay/`aget_state` (`aget_tuple()` with a `checkpoint_id`, `gitlab_workflow.py:1224-1247`) — partially covered by open, unmerged MR https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6363, gated on `DW_READ_BLOBS_API` + `incremental_checkpoints_enabled` - the pre-18.8 GraphQL fallback (`_fetch_most_recent_checkpoint()`, `gitlab_workflow.py:1005-1043`) `duo_workflow_write_incremental_only` isn't the defect — it's what turns the latent gap into actual data loss, by removing the legacy-row fallback these endpoints still depend on (`CreateCheckpointService#execute` skips writing the full row entirely under `write_incremental_only?`, `ee/app/services/ai/duo_workflows/create_checkpoint_service.rb:20-25`; the header row is still written whenever `incremental_checkpoints_enabled?`). There's a real-world precedent for this failure shape: https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/work_items/2775 (a checkpoint reported as missing → LangGraph `empty_checkpoint()` fallback → full state loss), previously caused by unpaginated fetching of this same endpoint. ### Fix Same reconstruction pattern as #612586, reusing `Gitlab::DuoWorkflow::ChannelValuesReconstructor`/`Workflow#reconstructed_channel_values`. Two design points specific to this consumer, unlike the single-object lookup in #612586: - `CheckpointHeader#checkpoint_writes` is a plain query method, not an eager-loadable `has_many` association (deliberately, since `BulkInsertSafe` forbids the autosave-triggering association) — the list/get endpoints currently rely on `.ordered_with_writes`/`.with_checkpoint_writes` (`includes(:checkpoint_writes)`) for N+1-safe eager loading, which has no direct equivalent on `CheckpointHeader` yet. - The list endpoint reconstructs N checkpoints per page (not just the latest one) — reconstructing each independently could be expensive (see the related finding that `duoMessages` reconstruction is roughly 60x heavier than a header-only read); batch-load blobs per page rather than per-checkpoint. **Reusable pattern:** open, unmerged MR https://gitlab.com/gitlab-org/gitlab/-/merge_requests/247134 adds a `by_thread_ts` single-checkpoint endpoint and already shows how to present a `CheckpointHeader` through the existing `Entities::Ai::DuoWorkflows::Checkpoint` entity — mutate the header before presenting: ```ruby header.checkpoint = header.checkpoint.merge( 'channel_values' => workflow.reconstructed_channel_values(header) ) header.compressed_checkpoint = compress_checkpoint(header.checkpoint) if params[:accept_compressed] present header, with: ::API::Entities::Ai::DuoWorkflows::Checkpoint ``` Note this MR only covers a point lookup by a known `thread_ts` — it can't replace the list endpoint or the pre-18.8 fallback (both need to enumerate/find "latest" without already knowing a `thread_ts`), so it doesn't reduce this issue's scope, but its presentation approach is directly reusable here. Since this is a REST (Grape) endpoint, not GraphQL, it doesn't hit the DeclarativePolicy gap from #612586's fix (GraphQL types authorize the raw object via `DeclarativePolicy`, which needed a new `CheckpointHeaderPolicy`; Grape entities have no equivalent per-class authorization step). ### Where - `ee/lib/api/ai/duo_workflows/workflows_internal.rb:141-243` - `ee/lib/api/entities/ai/duo_workflows/checkpoint.rb` - `ee/app/models/ai/duo_workflows/checkpoint_header.rb` (`checkpoint_writes` method) - `ee/app/services/ai/duo_workflows/create_checkpoint_service.rb:20-25` (why the legacy row goes missing) ### Acceptance criteria - [ ] Internal REST list endpoint returns reconstructed checkpoints for any `thread_ts` with no legacy row, alongside normal rows for workflows not on `write_incremental_only`. - [ ] Single-checkpoint reads work for header-only checkpoints. The existing `GET /checkpoints/:checkpoint_id` route cannot serve them, because the numeric id is the legacy table's primary key and a header has no such row. The new `by_thread_ts` route in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/247134 covers this, keyed on the identifier the gateway already holds; the gateway side is merged (https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6363). The numeric route stays legacy-only and is removed with the rest of the legacy read code in https://gitlab.com/gitlab-org/gitlab/-/work_items/611971. - [ ] Compressed-checkpoint response path (`accept_compressed`) still works against reconstructed data. - [ ] Plain checkpoint list response (no `accept_compressed`) must populate `checkpoint` with reconstructed `channel_values`, since `GetSessionContext` (`duo_workflow_service/tools/session_context.py:64-77`) reads `checkpoint["checkpoint"]["channel_values"]` for `goal`/`ui_chat_log` without sending `accept_compressed`, and a header-only shape would silently return a null `goal` instead of erroring. - [ ] No N+1 introduced for `checkpoint_writes` on the list endpoint. - [ ] Spec coverage for a workflow with a mix of legacy rows and incremental-only (header+blob-only) checkpoints. - [ ] `duo_workflow_write_incremental_only` rollout (https://gitlab.com/gitlab-org/gitlab/-/work_items/607029) unblocked once merged. ### Related - https://gitlab.com/gitlab-org/gitlab/-/work_items/612586 (same root cause, GraphQL latest/first checkpoint) - Rollout tracking: https://gitlab.com/gitlab-org/gitlab/-/work_items/607029 - Epic (incremental checkpoint read path): https://gitlab.com/groups/gitlab-org/-/work_items/22939 - AIGW partial fix (`aget_tuple` case only): https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6363 - Rails `by_thread_ts` endpoint (reusable presentation pattern, open/unmerged): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/247134 - Precedent incident: https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/work_items/2775