docs(android): add dual schedule native fetch and cache scope plan

Add ANDROID_DUAL_SCHEDULE_NATIVE_FETCH_AND_CACHE_SCOPE.md describing the
pre-implementation plan: WorkManager initial delay for dual prefetch,
NativeNotificationContentFetcher when URL is absent, and cacheScope on
ContentCache to separate dual vs daily reminder cache rows.

doc/platform/android/ANDROID_DUAL_SCHEDULE_NATIVE_FETCH_AND_CACHE_SCOPE.md

@@ -0,0 +1,113 @@
+# Android dual schedule: native fetch, WorkManager timing, and scoped content cache
+
+**Status:** Draft — implementation plan (pre-code)  
+**Date:** 2026-03-25  
+**Scope:** `daily-notification-plugin` Android (Kotlin/Java), dual / “New Activity” schedule (`scheduleDualNotification`)
+
+---
+
+## 1. Problem summary
+
+On Android, the dual schedule path today has three related gaps:
+
+1. **Prefetch does not use the native fetcher.** `FetchWorker` treats a missing `contentFetch.url` as mock JSON and never calls `NativeNotificationContentFetcher`, so host apps that omit `url` on purpose never see `TimeSafariNativeFetcher`-style behavior.
+
+2. **Prefetch runs at setup, not at `contentFetch.schedule`.** Dual scheduling calls `FetchWorker.enqueueFetch` with **no** initial delay, while the notify alarm is set for the next `userNotification.schedule` occurrence. The DB may record `dual_fetch_*` with `nextRunAt` for the fetch cron, but work is not aligned to that instant.
+
+3. **Cache is global.** `DualScheduleHelper` uses `contentCacheDao().getLatest()`, so any other feature (e.g. daily reminder prefetch writing the same table) can **overwrite** the row dual notify expects, or dual can overwrite data other features rely on.
+
+---
+
+## 2. Decisions (approved direction)
+
+| Area | Decision |
+|------|----------|
+| **Fetch timing** | **Option B:** Use **WorkManager** with **`setInitialDelay`** to the next `calculateNextRunTime(contentFetch.schedule)` (not an additional exact alarm for fetch in the first iteration). Keep **unique work name** `FetchWorker.WORK_NAME_DUAL` (`fetch_dual`) so `cancelDualSchedule` and daily reminder prefetch (`fetch_content`) stay isolated. |
+| **Exact alarms** | Accept **best-effort** timing under Doze/OEM; document that prefetch may run late. Revisit with a dedicated alarm only if field data requires stricter wall-clock behavior. |
+| **Native fetch** | When `url` is null/blank and `DailyNotificationPlugin.getNativeFetcherStatic()` is non-null, invoke **`NativeNotificationContentFetcher.fetchContent(FetchContext)`** with semantics aligned to `DailyNotificationFetchWorker` (timeout, metadata). Persist results into the **dual-scoped** cache (below). If `url` is set, preserve **HTTP GET** behavior for that path. |
+| **Cache sharing** | Add an explicit **`cacheScope`** (string) column on the content cache entity. Use well-known values (e.g. **`dual`**, **`daily`**, **`legacy`**). **Dual** reads/writes only **`dual`**; daily reminder writes **`daily`**; migration defaults old rows to **`legacy`** with documented read behavior. |
+
+---
+
+## 3. Implementation outline
+
+### 3.1 Dual prefetch scheduling (WorkManager + delay)
+
+- Compute `nextFetchAt = calculateNextRunTime(contentFetch.schedule)` using the same cron resolution as today for notify.
+- Compute `delayMs = max(0, nextFetchAt - now)`.
+- Build `OneTimeWorkRequest` for `FetchWorker` (or shared worker) with **`setInitialDelay(delayMs, MILLISECONDS)`**, existing constraints/backoff as appropriate, and **`InputData`** that identifies this run as **dual** (and passes `url`, timeouts, etc.).
+- **Reschedule:** After a successful run (or as part of the dual rollover story), enqueue the **next** dual prefetch for the following occurrence of `contentFetch.schedule` (parallel to notify rollover). **Boot recovery** must recompute delay from persisted dual config and re-enqueue `fetch_dual` if needed.
+
+### 3.2 `FetchWorker` / native path
+
+- When handling **dual** work with **no** `url`, call the **native fetcher** if registered; otherwise fall back policy should be explicit (mock only for dev, or failure — product choice).
+- Serialize native results to the same **payload** shape `DualScheduleHelper` already expects (JSON with `title` / `body` or `content`).
+- **Write** using **`cacheScope = dual`** (see §3.3).
+
+### 3.3 Room: `cacheScope` column
+
+- Add **`cacheScope: String`** to the `ContentCache` entity (name may match existing naming in the codebase).
+- Room migration: new column **NOT NULL** with default **`legacy`** for existing rows.
+- DAO:
+  - **`getLatestByScope(scope: String)`** (or equivalent) for dual and daily.
+  - Deprecate or narrow use of unscoped **`getLatest()`**; document which call sites must pass scope.
+
+### 3.4 `DualScheduleHelper`
+
+- Replace **`getLatest()`** with **`getLatestByScope("dual")`** (constant for the dual scope string).
+- Keep **`contentTimeout` / `fallbackBehavior`** logic unchanged; only the **source row** changes.
+
+### 3.5 Daily reminder and other writers
+
+- Any code path that populates `ContentCache` for the **daily** reminder should set **`cacheScope = daily`**.
+- Verify **all** `upsert` paths; avoid writing **`dual`** except from dual prefetch.
+
+### 3.6 Cancellation and isolation
+
+- **`cancelDualSchedule`:** Continue canceling **`fetch_dual`** only; do not cancel **`fetch_content`**.
+- No change to notify alarm IDs (`dual_notify_*` vs daily `notify_*` / app-specific ids) beyond what already exists.
+
+### 3.7 Tests
+
+- Delay math: next fetch in the future; past instant triggers immediate or “run now” branch per policy.
+- Native path invoked when `url` absent and fetcher registered; HTTP path unchanged when `url` set.
+- **Scope isolation:** Write **`daily`**, then **`dual`**, assert **`getLatestByScope("dual")`** is not the daily payload and **`DualScheduleHelper`** resolves dual copy correctly.
+- Boot / reschedule path re-enqueues **`fetch_dual`** with correct delay when dual config exists.
+
+### 3.8 Documentation
+
+- **CHANGELOG.md** and **README** (Android section): dual prefetch uses delayed WorkManager; content cache is **scoped**; integrators must not assume a single global cache row for all features.
+
+---
+
+## 4. Risks and mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| WorkManager runs **after** notify time | Document; consider retry or follow-up work item for stricter scheduling if needed. |
+| Missed migration for a writer | Grep for `ContentCache` / `upsert` / `getLatest` and audit. |
+| Old **`legacy`** rows | Dual helper reads **`dual`** only; legacy readers, if any, keep using **`legacy`** or explicit migration to **`daily`**. |
+
+---
+
+## 5. Out of scope (this iteration)
+
+- iOS parity for dual native fetch / timing (track separately if needed).
+- Replacing WorkManager with exact alarms for fetch (optional future enhancement).
+
+---
+
+## 6. References
+
+- Prior analysis: consuming app `doc/plugin-feedback-android-dual-schedule-native-fetch-and-timing.md` (external repo).
+- Plugin: `FetchWorker.kt`, `ScheduleHelper.scheduleDualNotification`, `DualScheduleHelper.kt`, `DailyNotificationFetchWorker.java`, `ContentCache` / DAO definitions.
+
+---
+
+## 7. Review checklist (before merge)
+
+- [ ] All `ContentCache` writes specify **`cacheScope`** intentionally.
+- [ ] `DualScheduleHelper` uses **scoped** read for **`dual`**.
+- [ ] `cancelDualSchedule` does not cancel **`fetch_content`**.
+- [ ] Boot path reschedules dual prefetch when appropriate.
+- [ ] CHANGELOG / README updated.