feat(workflows): serve stale workflows list while revalidating

[facumenzella]

Checklist

• If applicable, unit tests
• If applicable, create follow-up issues for purchases-android and hybrids

Motivation

Follow-up to #6961 (workflow detail stale-while-revalidate), addressing vegaro's review question: when the workflows list is stale, getWorkflowsList blocks the caller on the network. Whoever waits on onComplete (offerings delivery on the fresh-offerings path) eats a round-trip even though a usable offeringId -> workflowId map is already cached.

Stacked on #6961. Review/merge that first; this branches off it.

Description

getWorkflowsList now uses the same stale-while-revalidate shape as the detail, with one twist: for the list, the case that must block is an empty cache, not a stale one. You can serve a stale map (and cachedWorkflowId(forOfferingId:) already does, regardless of staleness), but you can't serve a map you've never fetched.

• fresh: onComplete immediately (unchanged)
• stale but present: serve the cached map (onComplete now), refresh + re-prefetch in the background
• cold / empty: block on the fetch, since cachedWorkflowId(forOfferingId:) must resolve once onComplete fires (this is what deliverEnsuringWorkflowsList relies on)

flowchart TD
    A([getWorkflowsList]) --> B{list cache stale?}
    B -->|no, fresh| FRESH["onComplete now"]
    B -->|yes| P{map already cached?}
    P -->|"yes (stale but present)"| SWR["capture generation G,<br/>onComplete now,<br/>refresh + re-prefetch in background"]
    P -->|"no (cold / empty)"| COLD["block: fetch, then onComplete<br/>(map must resolve before getOfferings returns)"]
    SWR --> WRITE["guarded list write"]
    COLD --> WRITE
    WRITE --> G{generation still G?}
    G -->|yes| OK["update map + prefetch details"]
    G -->|"no: clearCache on login/logout"| DROP["drop write,<br/>keeps prev user's map out"]

Loading

No new stale exposure: the in-memory map is already served stale by cachedWorkflowId(forOfferingId:) between refreshes today. This just stops blocking getOfferings on the refresh. The background list write stays generation-guarded (and the guarding generation is captured before serving), so the #6961 cross-user guarantee holds.

AI session context

Metadata

• PR: follow-up to feat(workflows): serve stale workflow detail while revalidating #6961, workflows list stale-while-revalidate
• Branch: facu/workflow-list-swr (stacked on facu/workflow-detail-swr)
• Author / human owner: facumenzella
• Agent(s): Claude Code (Opus 4.8, 1M context)
• Generated: 2026-06-09
• Context document version: 1

Goal

Give the workflows list the same stale-while-revalidate behavior as the detail, so a stale-but-present offeringId -> workflowId map is served immediately instead of blocking the caller on the network.

Initial Prompt

vegaro approved #6961 and asked "We need to do the same for getWorkflows right? Otherwise it blocks on a stale cache." After confirming the cache exposes a present-vs-empty distinction (cachedList.value != nil), the human asked to open this follow-up.

Agent Contribution

• Added WorkflowsCache.hasCachedWorkflowsList (lock-free, present-regardless-of-staleness).
• Split the list fetch body into fetchAndCacheWorkflowsList; getWorkflowsList now branches fresh / stale-present (serve + background refresh) / cold (block).
• Captured the background refresh's generation guard before serving (same fix codex flagged on feat(workflows): serve stale workflow detail while revalidating #6961's detail path), with an ifGeneration: param mirroring getWorkflow.
• Added shouldStoreGetWorkflowsCompletions / completeStoredGetWorkflows to MockWorkflowsAPI to control list-fetch timing.
• TDD: serve-stale-immediately test written first, watched fail (caller blocked) before implementing.

Human Decisions

• Do the list as a separate follow-up stacked on feat(workflows): serve stale workflow detail while revalidating #6961.
• Block only on the cold/empty cache; serve stale-but-present.

Files / Symbols Touched

• Sources/Purchasing/WorkflowManager.swift - getWorkflowsList, new fetchAndCacheWorkflowsList(... ifGeneration:).
• Sources/Caching/WorkflowsCache.swift - hasCachedWorkflowsList.
• Tests/UnitTests/Purchasing/WorkflowManagerTests.swift - 3 new tests.
• Tests/UnitTests/Mocks/MockWorkflowsAPI.swift - stored-completion support for getWorkflows.

Validation

• xcodebuild test (iPhone 15 sim): WorkflowManagerTests (51), OfferingsManagerTests, PurchasesWorkflowTests, WorkflowsCacheTests all green.
• swiftlint on changed files: clean.
• Manual verification: Not run.

Validation Gaps

• The drop-after-clear test drives the generation guard directly; the true sub-statement race (a clear between reading the served map and capturing the generation) is the same lock-free read window the cache accepts by design and isn't deterministically reproducible here.
• OfferingsManagerTests pass but were not confirmed to exercise the fresh-offerings + stale-but-present-list path specifically; that path is covered at the WorkflowManager level.

Review Focus

• The block case is empty/cold, not stale (you can't serve a map you don't have); deliverEnsuringWorkflowsList's "map resolves right after getOfferings" invariant still holds.
• Generation captured before onComplete on the SWR path; background write dropped on a racing clearCache().

Non-goals / Out of Scope

• The offerings cache. The detail SWR (its own PR, feat(workflows): serve stale workflow detail while revalidating #6961).

---

Note

Medium Risk
Changes offerings-adjacent list delivery and identity-generation guarding on background writes; behavior is well-tested but affects when getOfferings unblocks relative to network refresh.

Overview
getWorkflowsList now uses stale-while-revalidate for the workflows list, aligned with workflow detail and offerings: when the list is stale but already in memory, onComplete runs immediately and list fetch plus prefetch run in the background, so offerings delivery is not blocked on a network round-trip for a map that was already usable.

Only a cold/empty cache still blocks onComplete until the fetch (and prefetches) finish, preserving the invariant that cachedWorkflowId(forOfferingId:) can resolve after getOfferings when nothing was cached yet.

WorkflowsCache adds hasCachedWorkflowsList to distinguish present-vs-empty. List fetch logic moves into fetchAndCacheWorkflowsList, with the background refresh’s cache generation captured before serving so a late list write is dropped after login/logout. MockWorkflowsAPI gains deferred getWorkflows completions; three unit tests cover immediate stale serve, cold blocking, and generation-guarded drop on clear.

^{Reviewed by Cursor Bugbot for commit b57a78c. Bugbot is set up for automated code reviews on this repo. Configure here.}