feat(research): persist popularity metrics

[hubab1]

Summary

• add an app-independent Apple Ads popularity workflow for pre-live research-project keywords
• persist popularity on canonical shared queries without creating a fake tracked app, keyword track, or refresh status
• revalidate project/keyword incarnations and exact query scalars after provider suspension before one atomic write
• reuse the existing sequential Apple Ads CM client (100 terms per request), with a 500-keyword workflow cap, storefront grouping, seven-day cache policy, and structured partial outcomes
• wire the optional workflow through AppServices using the current context app and exact web-session reconnect state

Correctness and safety

• provider fetch and ModelContext persistence are split so the workflow owns rollback and commit
• all post-provider paths, including zero-evidence failures, revalidate generations and read the transaction-current cache
• concurrent newer popularity wins; difficulty-only rows neither masquerade as cached popularity nor suppress the first real popularity result
• missing context/session, reconnect-required, expiry, unsupported storefront, rate limiting, provider failures, cancellation, configuration changes, and not-found results have explicit outcomes
• provider messages and web-session secrets are never exposed in outcomes
• existing tracked apps, tracks, and refresh statuses remain unchanged; canonical derived ranking stats are rebuilt only after applied metric writes

Validation

• 49 focused metrics/workflow tests passed
• 405 full tests passed
• signed Debug build passed
• strict deep codesign verification passed
• three independent final P1/P2 reviews are clear
• Swift parsing, project-file lint, and diff checks passed

Stack and manual gate

This draft is stacked on #49 (33a-research-ranking-workflow) and is part of #3. It remains a manual persistence/provider acceptance gate and should not be auto-merged. The app was not launched against the maintainer's live store because the stack includes the V5 schema; signed build and codesign verification were used instead. The standalone MCP target membership is unchanged.

Known schema boundary

KeywordDailyMetric has no Apple Ads context dimension and only one legacy row timestamp. Persisted cache outcomes therefore report context as unknown, while the requested context is exposed only for evidence fetched by the current invocation. Settings/session revalidation and the SwiftData commit also cannot be globally atomic without a shared revision or lease; the exact configuration snapshot is rechecked immediately before the final write.

Attribution

Independent implementation for #3. No external co-author trailer is applicable.