Explain activity source priority decisions on detail

[Asherlc]

Summary

• Adds a server-derived sourceDecision on multi-source activity detail (sourceCount, primarySourceLabel, explanation) so clients do not recompute priority copy.
• Shows the same “How sources were combined” card on web and mobile activity detail.
• Completes the Data Trust Center roadmap outcome for explaining source conflicts / dedup priority (#2058); plan: docs/superpowers/plans/2026-07-26-activity-source-decision-explanation.md.

Test plan

• pnpm vitest run packages/server/src/models/activity-source-decision.test.ts packages/server/src/models/activity.test.ts
• pnpm vitest run packages/web/src/components/ActivitySourceDecisionCard.test.tsx packages/web/src/pages/ActivityDetailPage.test.tsx
• pnpm test:mobile
• pnpm lint (with local ClickHouse)
• pnpm tsc --noEmit + server/web package typechecks
• Open a multi-source activity on web and mobile and confirm the card matches the primary source label and explanation
• Confirm single-source activities do not show the card

---

Summary by cubic

Adds a server-owned sourceDecision for multi-source activities and shows a shared “How sources were combined” card on web and mobile. Explains the primary source and why, completing the Data Trust Center source-conflict outcome (#2058).

• New Features

  • Server returns sourceDecision with sourceCount, primarySourceLabel, and an explanation via Activity.toDetail() / activity.byId.
  • Web and mobile render ActivitySourceDecisionCard from server data; single-source activities don’t show the card.
  • Added stories on web and mobile for the card.

• Refactors

  • Web card uses useId to generate unique heading IDs for accessibility.
  • Activity.toDetail() computes sourceLinks once and is now the single path for sourceDecision (removed the unused Activity.sourceDecision getter).
  • Expanded server tests to cover custom primary labels and provider lookup fallbacks; formatted test files.

^{Written for commit 282e5cc. Summary will update on new commits.}

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[codereviewbot-ai]

🤖 Review skipped: Repository rate limit exceeded. Free accounts are limited to 2 reviews per 4 hours per repository. Upgrade to a paid plan for unlimited reviews.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Warning

Review limit reached

@Asherlc, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 23 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: c433cd54-b8eb-443e-b41b-06f508f0417f

📥 Commits

Reviewing files that changed from the base of the PR and between b3ec547 and 282e5cc.

📒 Files selected for processing (18)

• docs/roadmap.md
• docs/superpowers/plans/2026-07-26-activity-source-decision-explanation.md
• packages/mobile/app/activity/ActivitySourceDecisionCard.stories.tsx
• packages/mobile/app/activity/ActivitySourceDecisionCard.tsx
• packages/mobile/app/activity/[id].test.tsx
• packages/mobile/app/activity/[id].tsx
• packages/mobile/app/activity/styles.ts
• packages/server/src/models/activity-source-decision.test.ts
• packages/server/src/models/activity-source-decision.ts
• packages/server/src/models/activity.test.ts
• packages/server/src/models/activity.ts
• packages/server/src/routers/activity.test.ts
• packages/web/src/components/ActivitySourceDecisionCard.stories.tsx
• packages/web/src/components/ActivitySourceDecisionCard.test.tsx
• packages/web/src/components/ActivitySourceDecisionCard.tsx
• packages/web/src/pages/ActivityDetailPage.stories.tsx
• packages/web/src/pages/ActivityDetailPage.test.tsx
• packages/web/src/pages/ActivityDetailPage.tsx

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Add server-authored activity sourceDecision and parity detail card

✨ Enhancement 🧪 Tests 📝 Documentation 🕐 40+ Minutes

AI Description

• Add server-derived sourceDecision for multi-source activity detail to explain priority choice
• Render a shared “How sources were combined” card on both web and mobile activity detail
• Add unit/UI tests and update roadmap/plan docs for the Data Trust Center outcome

Diagram

graph TD
  A["Server: Activity model"] --> B["Server: SourceDecision builder"] --> C["API: activity.byId detail"] --> D["Web: Activity detail"] --> E["Web: Decision card"]
  C --> F["Mobile: Activity detail"] --> G["Mobile: Decision card"]
  A --> H["Docs: Roadmap & plan"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Client-derived decision (web/mobile recompute priority copy)

• ➕ No API shape change
• ➕ No server work required
• ➖ Duplicated logic and copy across platforms
• ➖ Higher risk of drift as provider priority rules evolve
• ➖ Harder to ensure consistent user-facing wording

2. Persist decision in analytics/db (materialized explanation)

• ➕ Decision is fully reproducible/auditable from stored evidence
• ➕ Could support “why did this change?” via versioning later
• ➖ Requires schema/ETL work and migration/backfill
• ➖ Overkill for a purely explanatory UI field derived from current canonical selection

3. Move `ActivitySourceDecisionDetail` to a shared types package

• ➕ Avoids web importing server source files directly
• ➕ Clarifies public API surface vs internal domain model types
• ➖ Extra packaging/workspace plumbing
• ➖ May be premature if the repo already standardizes on cross-package server type imports

Recommendation: The chosen approach (server-owned sourceDecision + render-only clients) is the best fit for the stated goal: it prevents cross-platform drift and keeps priority/explanation copy authoritative. The main follow-up to consider is whether API-facing types should live in a shared/public contract surface (or be inferred from the router) to reduce direct web→server source imports as the API evolves.

Files changed (18) +759 / -4

Enhancement (7) +184 / -2

ActivitySourceDecisionCard.tsxAdd mobile ActivitySourceDecisionCard component +28/-0

Add mobile ActivitySourceDecisionCard component

• Creates a small render-only card that displays source count, primary label, and server-authored explanation. Intended to be mounted from activity detail only when 'sourceDecision' is present.

packages/mobile/app/activity/ActivitySourceDecisionCard.tsx

[id].tsxRender source decision card on mobile activity detail +4/-0

Render source decision card on mobile activity detail

• Imports and mounts 'ActivitySourceDecisionCard' on the activity detail screen. The card is conditionally rendered only when 'activity.sourceDecision' is non-null.

packages/mobile/app/activity/[id].tsx

styles.tsAdd styling for mobile source decision card +38/-0

Add styling for mobile source decision card

• Introduces new style rules for the decision card container, title, key/value rows, and explanation text. Aligns spacing and typography with existing activity detail styling.

packages/mobile/app/activity/styles.ts

activity-source-decision.tsAdd ActivitySourceDecision domain builder +57/-0

Add ActivitySourceDecision domain builder

• Introduces 'buildActivitySourceDecision' to derive '{sourceCount, primarySourceLabel, explanation}' for activities with multiple source links. Primary label is resolved via matching source link first, then provider/subsource label fallbacks.

packages/server/src/models/activity-source-decision.ts

activity.tsExpose 'sourceDecision' on ActivityDetail and toDetail() +23/-2

Expose 'sourceDecision' on ActivityDetail and toDetail()

• Adds 'sourceDecision' to the 'ActivityDetail' API shape and exports its type. Implements an 'Activity.sourceDecision' getter that derives the decision from provider/subsource and existing 'sourceLinks', and includes it in 'toDetail()' output.

packages/server/src/models/activity.ts

ActivitySourceDecisionCard.tsxAdd web ActivitySourceDecisionCard component +30/-0

Add web ActivitySourceDecisionCard component

• Implements an accessible web card (section + heading + dl) that displays server-authored source decision fields. Uses existing design system classes for consistent styling on the activity detail page.

packages/web/src/components/ActivitySourceDecisionCard.tsx

ActivityDetailPage.tsxRender source decision card on web activity detail +4/-0

Render source decision card on web activity detail

• Imports and conditionally renders 'ActivitySourceDecisionCard' after the provider-absent banner. Keeps the client as a pure renderer of the server-provided decision payload.

packages/web/src/pages/ActivityDetailPage.tsx

Tests (6) +250 / -0

[id].test.tsxTest source decision card visibility on mobile activity detail +61/-0

Test source decision card visibility on mobile activity detail

• Extends the activity detail fixture with 'sourceDecision: null' and adds tests for showing the “How sources were combined” card when the server provides a decision. Verifies the card is hidden when 'sourceDecision' is null.

packages/mobile/app/activity/[id].test.tsx

activity-source-decision.test.tsAdd unit tests for building sourceDecision +81/-0

Add unit tests for building sourceDecision

• Adds coverage for null behavior on <2 sources, correct primary label selection (matching link label vs provider fallback), and consistent server-owned explanation copy. Exercises subsource matching behavior for Apple Health app sources.

packages/server/src/models/activity-source-decision.test.ts

activity.test.tsAssert Activity.toDetail() serializes sourceDecision correctly +19/-0

Assert Activity.toDetail() serializes sourceDecision correctly

• Extends existing Activity model tests to expect a populated 'sourceDecision' for multi-source fixtures. Adds an additional test ensuring 'sourceDecision' is null when only one source link exists.

packages/server/src/models/activity.test.ts

activity.test.tsIntegration test for activity detail includes sourceDecision +6/-0

Integration test for activity detail includes sourceDecision

• Extends router-level Activity model integration test assertions to verify 'sourceDecision' is returned alongside source attribution fields. Ensures the API contract is exercised end-to-end, not just via model unit tests.

packages/server/src/routers/activity.test.ts

ActivitySourceDecisionCard.test.tsxAdd unit test for web source decision card rendering +29/-0

Add unit test for web source decision card rendering

• Adds a jsdom test verifying the heading, source count, primary label, and explanation render from the server-provided decision. Confirms the component is render-only and does not derive any logic itself.

packages/web/src/components/ActivitySourceDecisionCard.test.tsx

ActivityDetailPage.test.tsxTest source decision card show/hide behavior on web activity detail +54/-0

Test source decision card show/hide behavior on web activity detail

• Extends the page test fixture with 'sourceDecision: null' and adds tests verifying the card renders for multi-source activities and is omitted when the decision is null. Ensures page-level wiring works, not just the card component itself.

packages/web/src/pages/ActivityDetailPage.test.tsx

Documentation (2) +247 / -2

roadmap.mdReframe roadmap as Product Strategy and mark Trust Center outcome +141/-2

Reframe roadmap as Product Strategy and mark Trust Center outcome

• Rewrites the roadmap framing from “Near-Term Product Opportunities” to “Product Strategy” and expands the product gate/outcomes narrative. Marks the Data Trust Center checkbox for explaining source conflicts/priority decisions as completed.

docs/roadmap.md

2026-07-26-activity-source-decision-explanation.mdAdd TDD plan for activity source decision explanation +106/-0

Add TDD plan for activity source decision explanation

• Introduces a detailed test-driven plan covering server domain modeling, API serialization, and web/mobile parity UI for multi-source activity explanations. Documents scope, non-goals, tasks, and verification steps for the Data Trust Center slice.

docs/superpowers/plans/2026-07-26-activity-source-decision-explanation.md

Other (3) +78 / -0

ActivitySourceDecisionCard.stories.tsxAdd Storybook stories for mobile source decision card +39/-0

Add Storybook stories for mobile source decision card

• Adds React Native Storybook coverage for multi-source and three-source variants. Uses server-style copy and fields to validate visual parity with web.

packages/mobile/app/activity/ActivitySourceDecisionCard.stories.tsx

ActivitySourceDecisionCard.stories.tsxAdd Storybook stories for web source decision card +38/-0

Add Storybook stories for web source decision card

• Adds Storybook coverage for multi-source and three-source scenarios using consistent copy and fields. Wraps the story to constrain width and match activity detail layout expectations.

packages/web/src/components/ActivitySourceDecisionCard.stories.tsx

ActivityDetailPage.stories.tsxUpdate activity detail Storybook fixture for new sourceDecision field +1/-0

Update activity detail Storybook fixture for new sourceDecision field

• Updates the base ActivityDetail story fixture to include 'sourceDecision: null'. Keeps Storybook data aligned with the updated ActivityDetail type contract.

packages/web/src/pages/ActivityDetailPage.stories.tsx

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 199 rules

✅ Skills: fix-provider, write-tests, cloudflare

1. Duplicate heading ID ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

ActivitySourceDecisionCard hard-codes id="activity-source-decision-heading" (and
aria-labelledby referencing it), which will produce duplicate DOM ids if the card is ever rendered
more than once in the same document and can break accessibility labeling.

Code

packages/web/src/components/ActivitySourceDecisionCard.tsx[R10-16]

+    <section
+      className="mb-4 rounded-lg border border-border bg-surface p-4"
+      aria-labelledby="activity-source-decision-heading"
+    >
+      <h2 id="activity-source-decision-heading" className="text-sm font-semibold text-foreground">
+        How sources were combined
+      </h2>

Relevance

⭐⭐⭐ High

Repo has a pattern of accepting accessibility hardening (ARIA improvements); unique heading ids
likely welcomed.

PR-#1197
PR-#2045

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The component sets a constant aria-labelledby value and a constant matching h2 id, which will be
duplicated across instances.

packages/web/src/components/ActivitySourceDecisionCard.tsx[10-16]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`ActivitySourceDecisionCard` uses a fixed heading id (`activity-source-decision-heading`) for `aria-labelledby`. If multiple cards are rendered on the same page, this creates duplicate DOM ids and ambiguous labeling.

### Issue Context
This is a reusable component; future reuse (or story/pages that mount multiple cards) will violate unique-id requirements.

### Fix Focus Areas
- packages/web/src/components/ActivitySourceDecisionCard.tsx[10-16]

### Suggested fix
- Use `useId()` to generate a per-instance id and apply it to both `aria-labelledby` and the `<h2 id=...>`.
 - Example:
   - `const headingId = useId();`
   - `aria-labelledby={headingId}`
   - `<h2 id={headingId} ...>`
- (Optional) Add an `idBase` prop if deterministic ids are desired for tests.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Source links computed twice ✓ Resolved 🐞 Bug ➹ Performance

Description

Activity.toDetail() calls this.sourceLinks for the serialized payload and also calls
this.sourceDecision, whose getter calls this.sourceLinks again; sourceLinks construction does
mapping/filtering/sorting, so this duplicates work on every activity.byId response.

Code

packages/server/src/models/activity.ts[R199-202]

      subsource: this.subsource,
      sourceProviders: this.sourceProviders,
      sourceLinks: this.sourceLinks,
+      sourceDecision: this.sourceDecision,

Relevance

⭐⭐⭐ High

Team has accepted avoiding duplicated computation in render/serialization paths; caching once is
favored.

PR-#1359

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The sourceDecision getter calls buildActivitySourceDecision(..., this.sourceLinks, ...) and
toDetail() separately reads this.sourceLinks and this.sourceDecision. toSourceLinks()
performs mapping/filtering/sorting, so recomputation is real work.

packages/server/src/models/activity.ts[128-130]
packages/server/src/models/activity.ts[180-205]
packages/server/src/models/activity-source-attribution.ts[71-83]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`Activity.toDetail()` currently triggers two `sourceLinks` computations: one directly for `sourceLinks`, and one indirectly via `sourceDecision` (which calls `this.sourceLinks`). This repeats mapping/filtering/sorting work.

### Issue Context
`sourceLinks` is not a trivial getter; it calls `ActivitySourceAttribution.toSourceLinks(...)`, which maps entries, filters absent links, and sorts.

### Fix Focus Areas
- packages/server/src/models/activity.ts[128-130]
- packages/server/src/models/activity.ts[180-205]
- packages/server/src/models/activity-source-attribution.ts[71-83]

### Suggested fix
- In `toDetail()`, compute `const sourceLinks = this.sourceLinks;` once.
- Compute `const sourceDecision = buildActivitySourceDecision(this.providerId, this.subsource, sourceLinks, this.#lookupProvider);` (or refactor the getter to accept precomputed links).
- Return `{ sourceLinks, sourceDecision, ... }` to avoid recomputation.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Test state leak risk 🐞 Bug ☼ Reliability

Description

ActivityDetailPage tests mutate the shared mockActivity object and restore it only at the end of
the test; if the test throws before restoration, subsequent tests can run with polluted fixture
state and become order-dependent.

Code

packages/web/src/pages/ActivityDetailPage.test.tsx[R805-849]

+    it("shows how sources were combined when the server returns a source decision", async () => {
+      const originalData = { ...mockActivity };
+      Object.assign(mockActivity, {
+        providerId: "wahoo",
+        subsource: null,
+        sourceProviders: ["wahoo", "strava"],
+        sourceLinks: [
+          {
+            providerId: "strava",
+            externalId: "99999",
+            subsource: null,
+            label: "Strava",
+            url: "https://www.strava.com/activities/99999",
+            providerAbsentAt: null,
+          },
+          {
+            providerId: "wahoo",
+            externalId: "42",
+            subsource: null,
+            label: "Wahoo",
+            url: "https://systm.wahoofitness.com/history/activity-details/42",
+            providerAbsentAt: null,
+          },
+        ],
+        sourceDecision: {
+          sourceCount: 2,
+          primarySourceLabel: "Wahoo",
+          explanation:
+            "Wahoo was selected as the primary record by source priority. Missing details may come from the other matched sources.",
+        },
+      });
+
+      const ActivityDetailPage = await importPage();
+      renderWithUnits(<ActivityDetailPage />);
+
+      expect(screen.getByRole("heading", { name: "How sources were combined" })).toBeTruthy();
+      expect(screen.getByText("2")).toBeTruthy();
+      expect(
+        screen.getByText(
+          "Wahoo was selected as the primary record by source priority. Missing details may come from the other matched sources.",
+        ),
+      ).toBeTruthy();
+
+      Object.assign(mockActivity, originalData);
+    });

Relevance

⭐ Low

Closely analogous suggestion to prevent mockActivity mutation leaks via afterEach/try-finally was
explicitly rejected.

PR-#1964

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The test modifies mockActivity with Object.assign and only restores it at the end of the test,
which won’t execute if earlier assertions throw.

packages/web/src/pages/ActivityDetailPage.test.tsx[805-849]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Tests mutate a shared `mockActivity` via `Object.assign(...)` and restore it at the end of the test body. If an assertion fails (or an unexpected throw happens), the restore line won’t run, potentially breaking later tests.

### Issue Context
This pattern appears in the newly added source decision card tests.

### Fix Focus Areas
- packages/web/src/pages/ActivityDetailPage.test.tsx[805-849]

### Suggested fix
Prefer one of:
- Build a fresh activity object per test (no shared mutation).
- Or wrap mutation/restoration in `try { ... } finally { Object.assign(mockActivity, originalData); }`.
- Or move restoration into an `afterEach` that always resets `mockActivity`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[codereviewbot-ai]

🤖 Review skipped: Repository rate limit exceeded. Free accounts are limited to 2 reviews per 4 hours per repository. Upgrade to a paid plan for unlimited reviews.

[Asherlc]

Addressed Qodo review feedback in 0a21a3f:

• Web card heading ids now use React useId() to avoid duplicate DOM ids.
• Activity.toDetail() computes sourceLinks once and reuses that list for sourceDecision.

[github-actions]

Mobile Preview

Scan to open on device:

Channel	pr-2204
Deep Link	dofek://preview/pr-2204
Commit	26bbd55

To test on device:

1. Build and install the preview client: PREVIEW_CHANNEL=pr-2204 pnpm expo prebuild --clean -p ios
2. Or tap deep link on an existing preview build: dofek://preview/pr-2204

Each PR gets its own channel. Build a preview client with PREVIEW_CHANNEL=pr-{N} to test.

[sourcery-ai]

Sorry @Asherlc, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[github-actions]

Storybook previews for 26bbd554 are ready:

• Web Storybook
• Mobile Storybook

This comment updates automatically on each PR push.

[codereviewbot-ai]

🤖 Review skipped: Repository rate limit exceeded. Free accounts are limited to 2 reviews per 4 hours per repository. Upgrade to a paid plan for unlimited reviews.

[codereviewbot-ai]

🤖 Review skipped: Repository rate limit exceeded. Free accounts are limited to 2 reviews per 4 hours per repository. Upgrade to a paid plan for unlimited reviews.