# `:provider` — provenance

This module is **not our code**. It is the dmfs task provider, vendored, with
its namespace renamed to ours and a short list of changes recorded below.

| | |
|---|---|
| Upstream | [dmfs/opentasks](https://github.com/dmfs/opentasks) |
| Module taken | `opentasks-provider`, plus `opentasks-contract` (see [Why the contract came along](#why-the-contract-came-along)) |
| Version | `1.4.2` |
| Commit | `49ebf80b1eeee52a611e5a22f24f849852a6255f` (2021-03-21) |
| License | Apache-2.0 — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE), both upstream's, unmodified |
| Database version | **23** |

Agendula itself is MIT. Apache-2.0 into MIT is fine in that direction, but this
module keeps its own `LICENSE`, `NOTICE`, and per-file Apache headers, and those
must survive any future edit here.

**1.4.2 specifically, for the database version.** DB 23 is the first to carry
`is_recurring`. tasks.org's fork is DB 22 and lacks it — which is why
`TaskMapper.task` on the app side derives recurrence from `rrule`/`rdate`
instead of trusting that column, and why it must keep doing so as long as
External mode supports tasks.org.

## Why vendored at all

Recorded properly in [`docs/STORAGE-AND-SYNC.md`](../docs/STORAGE-AND-SYNC.md);
in one line: **the permission names are hardcoded in the upstream AAR's
manifest.** No prebuilt artifact — Maven Central, JitPack, anything — can have
them renamed without `tools:` node surgery, and shipping under dmfs's own
permission names would make Agendula and OpenTasks mutually uninstallable
(`INSTALL_FAILED_DUPLICATE_PERMISSION`). In-tree also satisfies F-Droid's
from-source requirement, which a JitPack artifact would not.

In-tree rather than a git submodule, unlike floret-kit: we co-develop the kit,
whereas this is a fork we expect to resync from upstream approximately never.

## The namespace rename

Everything in this table is a rename and nothing more. The **contract shape is
untouched** — same tables, same column names, same URI paths — because that
shape is what our data layer, and every CalDAV engine, already speaks. We own
the namespace it lives in, not the schema.

| | Upstream | Ours |
|---|---|---|
| Authority | `org.dmfs.tasks` | `de.jeanlucmakiola.agendula.tasks` |
| Read permission | `org.dmfs.permission.READ_TASKS` | `de.jeanlucmakiola.agendula.permission.READ_TASKS` |
| Write permission | `org.dmfs.permission.WRITE_TASKS` | `de.jeanlucmakiola.agendula.permission.WRITE_TASKS` |
| Permission group | `org.dmfs.tasks.permissiongroup.Tasks` | `de.jeanlucmakiola.agendula.permissiongroup.Tasks` |
| Notification-alarm action | `org.dmfs.tasks.provider.NOTIFICATION_ALARM` | `de.jeanlucmakiola.agendula.provider.NOTIFICATION_ALARM` |
| Resource prefix | `opentasks_*` | `agendula_*` |
| R class | `org.dmfs.tasks.provider.R` | `de.jeanlucmakiola.agendula.provider.R` |

### What was deliberately *not* renamed

- **Java package names** stay `org.dmfs.provider.tasks` / `org.dmfs.tasks.contract`.
  They are not a registered namespace — two apps may share them freely — and
  keeping them means the diff against upstream stays legible. Only the AGP
  `namespace` (which decides where `R` lands) is ours.
- **`TaskContract.LOCAL_ACCOUNT_TYPE`** stays `"org.dmfs.account.LOCAL"`. It is a
  value stored in the database and recognised by dmfs-contract providers
  generally, so the *same* app code has to write it whether it is talking to our
  provider or, in External mode, to OpenTasks. Renaming it would fork the write
  path in two for no gain.
- **`ACTION_BROADCAST_TASK_DUE` / `…_TASK_STARTING` / `ACTION_DATABASE_INITIALIZED`.**
  Every send site calls `setPackage()` on its own package first, so these never
  cross app boundaries and cannot collide with an installed OpenTasks.

## Changes to upstream source

Four files under `src/main/java`, one under `src/test/java`. Each edit is marked
with an `AGENDULA CHANGE` comment at the site, so this list and the code cannot
drift apart. Keep that convention.

### Behavioural

1. **`Utils.cleanUpLists` — only prune account types we authenticate ourselves.**
   *The one change here that is about correctness rather than mechanics.*

   Upstream holds `GET_ACCOUNTS` and enumerates every account on the device. We
   dropped that permission (below), so `AccountManager` only ever reports
   accounts of our own type. Upstream's cleanup deletes any task list whose
   account is absent from that array — and an account we *cannot see* is
   indistinguishable from one that has been *removed*. Left alone, the provider
   would quietly delete synced lists. Not "sync stops": data disappears, with no
   error anywhere.

   Now a list is only prunable when its account type belongs to an authenticator
   in **this package**. Agendula ships no authenticator yet, so the set is empty
   and nothing is ever pruned; our sync adapter's type will join it on its own
   when it lands, no edit needed here. Local lists were already exempt upstream.

2. **`TaskProvider.insert` — the same restriction for the stale-list signal.**
   Upstream flags "list with unknown account" and broadcasts about it. With the
   account cache holding only our own accounts, that fired on every insert into
   any externally-synced list. Nothing listens today; the point is that whatever
   listens tomorrow gets a signal that means something.

3. **`TaskProviderBroadcastReceiver.onReceive` — fall-through written out.**
   Upstream's `switch` has no `break` in any branch, so `TIMEZONE_CHANGED` runs
   all three content operations and `NOTIFICATION_ALARM` runs the last two. The
   comment on the first branch ("don't trigger the notifications update yet")
   describes breaks that were never written, so the code and the stated intent
   contradict each other.

   **Observed behaviour is preserved exactly**, just spelled out with `if`s
   rather than reached by accident. A vendored fork is the wrong place to guess
   at intent. ⚠️ **Open:** which of the two is the bug wants a device with a task
   due across a timezone change to settle.

4. **`TaskProviderBroadcastReceiver.planNotificationUpdate` — inexact-alarm fallback.**
   `setExact` throws `SecurityException` on API 31–32 when the user revokes
   `SCHEDULE_EXACT_ALARM` — inside a receiver handling a system broadcast, so the
   app would die on every timezone change. Falls back to `set` when exact alarms
   aren't permitted. This alarm drives only the provider's own bookkeeping;
   Agendula's user-visible reminders come from `ReminderScheduler`, which asks
   for the permission properly.

### Required by modern Android (would not build or would crash otherwise)

5. **`PendingIntent.FLAG_IMMUTABLE`** added in `planNotificationUpdate`. Mandatory
   since Android 12; throws `IllegalArgumentException` without it at targetSdk ≥ 31.
   Upstream targets 29. Nothing mutates the intent later, so immutable is also
   correct on the merits.
6. **`android:exported`** stated explicitly on the receiver. AGP hard-errors on an
   intent-filtered component without it at targetSdk ≥ 31.
7. **`package=` attribute** removed from the manifest; AGP 8+ takes it from the
   `namespace` in the build file.
8. **`<uses-sdk tools:overrideLibrary="org.dmfs.android.contenttestpal"/>`** removed
   along with the androidTest sources it existed for (below).

### Permissions

9. **`android.permission.GET_ACCOUNTS` dropped.** We only ever need to see
   accounts of our own type, and since API 26 an authenticator makes those
   visible to its own package with no grant at all. Safe **only** in combination
   with change 1 — the two must be read together.

### Build and test

10. **`build.gradle` → `build.gradle.kts`**, on the root version catalog. minSdk
    21 → 29 (matching `:app`; the merger rejects a lower floor), Java 8 → 17.
11. **Test stack modernised**, sources otherwise untouched: JUnit 4.12 → 4.13.2,
    Robolectric 3.5.1 → 4.16, Mockito 2.27 → 5.20, Hamcrest 1.3 → 3.0.
    `org.dmfs:jems`, `rfc5545-datetime` and `lib-recur` stay on the versions
    upstream pinned — all three resolve from Maven Central, so no new repository
    was added (`settings.gradle.kts` is still `google()` + `mavenCentral()` under
    `FAIL_ON_PROJECT_REPOS`).
12. **`ZippedTest.testAbsent`** — diamond `new Zipped<>` given an explicit type
    argument. `absent()` pins no type, and javac 17 will not infer what javac 8
    did. The assertion is unchanged.
13. **`src/test/resources/robolectric.properties` added** (`sdk=34`,
    `conscryptMode=OFF`). A library module has no `targetSdk` for Robolectric to
    read, and Robolectric installs Conscrypt unconditionally, whose uber jar has
    no `linux-aarch_64` native — so without this the suite fails at setup on ARM64
    machines while passing on x86_64 CI. See the file for the reasoning.
14. **`src/androidTest` dropped entirely.** It depends on `contentpal` /
    `contenttestpal`, which are JitPack-only; adding JitPack would widen the
    dependency trust surface for test-only code. ⚠️ This is the one place
    vendoring lost coverage — those were the provider's *integration* tests
    (recurrence, reparenting, instances, observers). The 56 JVM tests in
    `src/test` all pass and are retained.
15. **`agendula_provider_changed_receivers` emptied.** Upstream notifies
    `org.andstatus.todoagenda`, which listens for changes to the *dmfs* authority
    and has never heard of ours. Anything re-added here also needs a `<queries>`
    entry in the app manifest or package-visibility rules drop the broadcast.
16. **Translated `agendula_provider_label` overrides removed** (the other
    translated strings are kept as upstream shipped them). The base label became
    "Agendula tasks" so it is distinguishable from OpenTasks' own "Tasks" entry in
    the system permission dialog; the inherited translations still said plain
    "Tasks" in their language, which would have contradicted it.

## Resyncing from upstream

Unlikely to ever be worth it — upstream 1.4.2 is from 2021 — but if it is: the
`AGENDULA CHANGE` markers are the complete list of what to reapply, `git log` on
this directory is the audit trail, and the 56 JVM tests are the safety net.
Re-read change 1 before touching anything account-related.

## Known-unverified

Everything here is verified by the JVM test suite and a clean build. What is
**not** yet verified on a device with real data:

- The local-list path with **no account present at all** — the entirety of Local
  mode. `cleanUpLists` exempts local lists explicitly and change 1 makes the
  prunable set empty, so it should hold by construction; it is covered by
  `ProviderAccountCleanupTest`, but that is Robolectric, not a device.
- The timezone-change behaviour in change 3.
- Any interaction with an external sync engine writing into our authority
  (nothing does yet — that is the DAVx5 ask, step 4 of the sequencing).