agendula/docs/STORAGE-AND-SYNC.md

# Agendula — storage and sync

> ⚠️ **Partly superseded, 2026-08-13.** The core decision below — *vendor the
> dmfs provider in-tree as `:provider`* — has been **reversed**. Agendula builds
> its own Room store and deletes the vendored provider; External mode (OpenTasks,
> tasks.org) is unaffected and everything this document says about it still
> stands. See [`STORAGE-DECISION.md`](STORAGE-DECISION.md) for why and
> [`OWN-STORE.md`](OWN-STORE.md) for what replaces it. The permissions,
> distribution, storage-mode and dead-end sections below remain accurate; treat
> the "our own provider" sections as the historical record of a decision that was
> made, shipped, and then costed properly.

> Decided direction, captured 2026-08-01. Supersedes the earlier "Posture B =
> bundle OpenTasks" working notes, which are withdrawn (see
> [Dead ends](#dead-ends--do-not-revisit)). This is the detailed companion to
> `ARCHITECTURE.md` §7 and the `ProviderResolver` comments, **and it redefines
> what Posture B means.**
>
> **Status, 2026-08-02: steps 1–3 are done** — see
> [Sequencing](#sequencing). `ARCHITECTURE.md` and `ROADMAP.md` have had their
> follow-up pass and now match what shipped; `PLAN.md` is the original design
> document and is left as the historical record. What is built, and what is still
> only described here, is marked step by step below.

## The plan, in short

**What we're building**

1. **Our own provider.** Vendor the Apache-2.0 dmfs task provider in-tree as
   `:provider`, renamed to our own authority and permission namespace. Our
   database, our namespace — coexists with everything, replaces nothing.
2. **Our own sync.** An Agendula sync adapter, so remote storage never depends
   on another app's roadmap.
3. **The user picks the mode.** Local-only · Synced · External provider.
4. **Least permission.** Ask only for what the chosen mode needs, when it needs
   it.
5. **Kit-first.** Anything that isn't task-domain goes to floret-kit.

**In what order**

| # | Step | Why now | Status |
|---|---|---|---|
| 1 | Merge `fix/provider-interaction-review` | unmerged and rotting; touches the same permission flow as step 2 | ✅ done |
| 2 | Vendor `:provider` under our own authority | the identity, done once — and it ships a complete local-first app | ✅ done |
| 3 | Export / backup | our data now lives only in our app's private storage | ✅ done, UI included |
| 4 | File the DAVx5 issue | cheap, non-blocking, serves F-Droid users | ⬜ |
| 5 | Sync adapter | the 1.x arc; designed in [`SYNC.md`](SYNC.md), not yet built | ⬜ |

Everything below is the reasoning behind those choices, the alternatives that
were rejected, and the constraints they have to survive.

---

## The decision

Agendula gets its **own identity all the way down** — its own task database
under its own authority, its own sync, and a storage mode the user picks. It
does not adopt, replace, or impersonate another project's provider.

Four parts:

1. **Own DB, bundled in-process.** Vendor the Apache-2.0 dmfs
   `opentasks-provider` as an in-tree `:provider` Gradle module, renamed to
   authority `de.jeanlucmakiola.agendula.tasks` with permissions
   `de.jeanlucmakiola.agendula.permission.READ_TASKS` / `…WRITE_TASKS`. Not a
   separate provider *app*; not a schema written from scratch. We keep the dmfs
   `TaskContract` shape — it's proven, it's what our whole data layer already
   speaks, and it's what every CalDAV engine already understands — we just own
   the namespace it lives in.
2. **Own sync adapter**, so remote storage never depends on another app's
   roadmap. Protocol coverage is deliberately open — separate discussion.
3. **The user chooses the backend**: local-only, synced, or an external provider
   that's already on the device.
4. **Ask for only what the chosen mode actually needs**, at the moment it needs
   it.

Plus a standing rule: **anything that isn't task-domain goes to floret-kit.**

### The vocabulary, redefined

`ARCHITECTURE.md` §7 and `ProviderResolver`'s KDoc used to describe Posture B as
"bundle OpenTasks and find `org.dmfs.tasks` first." Both now read as below:

- **Posture A** — front-end over an *external* provider (OpenTasks, tasks.org).
  Still fully supported; it stops being the default and becomes a **user
  choice**.
- **Posture B** — our own bundled provider under **our own** authority.
  Coexists with everything; replaces nothing.

The A/B seam itself is unchanged and still earns its keep: `ProviderResolver` is
the only thing that knows an authority, `AndroidTasksDataSource` the only thing
that touches a resolver. UI, ViewModels, domain and repository are untouched by
all of this.

---

## Why not squat `org.dmfs.tasks`

The rejected plan was to bundle the provider under dmfs's own authority so
DAVx5 would sync into it unwittingly. Reasons it's out, in order of how badly
each one bites:

1. **It is a structural identity mismatch, and the resulting bug is invisible to
   both sides.** Content-provider *authorities* are how a sync engine finds a
   provider, but Android **account visibility is keyed by package name**: since
   API 26 an app only sees accounts whose authenticator has made them visible to
   *its package*, and `GET_ACCOUNTS` alone no longer suffices. A sync engine's
   allowlist would name the package `org.dmfs.tasks`, not
   `de.jeanlucmakiola.agendula`. So the bundled provider could find **zero**
   accounts — and the dmfs provider uses account enumeration to prune task lists
   whose account has gone away. The failure mode isn't "no sync", it's "our
   provider quietly purges synced lists." *(Reasoned from the platform rules,
   not from having read DAVx5's source — but the class of bug is structural, and
   every future place anything keys on package rather than authority is a fresh
   instance of it.)* An explicit integration under our own name makes this bug
   impossible by construction.
2. **Play Store install-time landmine.** Two apps cannot declare the same
   authority (`INSTALL_FAILED_CONFLICTING_PROVIDER`) or the same `<permission>`
   name (`INSTALL_FAILED_DUPLICATE_PERMISSION`, waived only for identical
   signing certs). Anyone with OpenTasks installed gets a failed install,
   surfacing as one-star reviews we can't usefully answer.
3. **Migration data loss.** "Uninstall OpenTasks first" takes its DB with it.
   CalDAV-synced tasks reconcile back; local-only tasks are simply gone, and
   OpenTasks has no export (dmfs/opentasks #170, #204, #71 — years-old,
   unimplemented; their wiki punts to a desktop client).
4. **Squatting another project's namespace doesn't scale.** At low install
   counts nobody notices. At scale we'd be generating issues on dmfs's tracker
   that aren't dmfs's fault, and silently maintaining a schema fork under their
   name.

---

## The `:provider` module

**Source.** dmfs `opentasks-provider`, Apache-2.0. Target the **1.4.2** source
(DB version 23 — the version that actually carries `is_recurring`; tasks.org's
fork is DB 22 and lacks it, which is why `TaskMapper.task` reads `rrule`/`rdate`
for recurrence detection rather than trusting the column).

**Layout: in-tree module, not a git submodule.** floret-kit is a submodule
because we co-develop it. This is a fork we will sync from upstream
approximately never, so in-tree is simpler for both stores and honest about what
it is. Ship a `provider/PROVENANCE.md`: upstream commit, and every change we
made.

**License hygiene, on day one.** The app is MIT, the provider is Apache-2.0 —
permissive into permissive, fine — but the module keeps its Apache-2.0 headers,
`LICENSE`, and `NOTICE`. Ten minutes now; embarrassing to retrofit once it's in
two store listings.

**What we change:**

- Authority → `de.jeanlucmakiola.agendula.tasks` (it's already a string
  resource, `opentasks_authority`).
- Permission names → `de.jeanlucmakiola.agendula.permission.*`. These are
  **hardcoded in the AAR manifest**, which is the single clearest reason
  vendoring is mandatory rather than merely preferable — you cannot rename them
  in a prebuilt artifact without `tools:` node surgery we'd rather not ship.
- Drop `<uses-permission android:name="android.permission.GET_ACCOUNTS" />`.
  We own our own accounts, so we don't need it — but note the provider's
  account-cleanup path is written *assuming* it, so this is a review-and-rework
  item, not a free deletion. **Verify** the provider's local-list/local-account
  path works with no account present at all; that's the entire local-only mode.
- Drop the exported `BOOT_COMPLETED` / `TIME_SET` / `TIMEZONE_CHANGED` receiver,
  or keep it deliberately and give it an explicit `android:exported`. The AAR is
  from the `targetSdk 29` era; AGP hard-errors on a merged manifest with an
  intent-filtered component and no explicit `exported` once targetSdk ≥ 31, and
  we're on 36. Fixed at source instead of patched around.
- Modernize the build: it ships `minSdk 21` / `targetSdk 29`, Robolectric 3.5.1,
  JUnit 4.12. We're `minSdk 29` / `targetSdk 36` and Play raises its target-API
  floor annually, so this isn't optional upkeep.

**Our data now lives in our app's private storage.** Uninstall means deletion.
That single fact is what promotes export/backup from "nice to have" to a v1
feature — see [Storage modes](#storage-modes--the-users-choice).

---

## Storage modes — the user's choice

| Mode | Backing store | Sync | Needs |
|---|---|---|---|
| **Local** | our bundled provider | none | no permissions at all — same-uid provider access needs no grant |
| **Synced** | our bundled provider | our sync adapter | network + an account the user configures |
| **External** | OpenTasks / tasks.org | whatever that provider's engine does (DAVx5 …) | that provider's `READ`/`WRITE_TASKS`, granted at runtime |

Local and Synced are the same store — but ⚠️ **switching on sync *is* a
migration, contrary to what this document said until 2026-08-13.** The provider
enforces `ACCOUNT_NAME` and `ACCOUNT_TYPE` as **write-once** on a task list
(`processors/lists/Validating.java:68-76`, which throws), so a list created under
`org.dmfs.account.LOCAL` can never be re-pointed at a real account. Enabling sync
means creating new lists under the account and moving tasks into them. See
[`SYNC.md`](SYNC.md) — it is a costed deliverable there, not a free consequence.

**Resolver ordering — decided, and it went both ways as expected.**
`ProviderResolver` now takes an explicit `StorageMode` from Settings when there
is one, and otherwise calls `autoMode()`. The auto rule turned out to be sharper
than "rank ours first whenever it's non-empty", and needs no database probe:

> **External if we already hold an external provider's runtime permission,
> otherwise Local.**

That permission is dangerous-level, so it can only be there because an earlier
version asked and the user agreed — which is exactly what "existing Posture A
user" means. A fresh install holds nothing and gets local-first. ✅ The Settings
override the rule assumes is built: Storage → Task store, which asks for the
external provider's permission before committing the switch rather than after.

**Note on the mode vocabulary.** The code has two modes, not three:
`StorageMode.LOCAL` and `StorageMode.EXTERNAL`. As this document says two
paragraphs up, Synced *is* Local with an account attached — so it is derived
state, and giving it its own constant would imply switching sync on is a
migration when the whole point is that it isn't.

**Export/backup is a v1 feature.** ✅ Built, screen included. Not, as
previously framed, a migration safety net for "uninstall OpenTasks" — that
scenario no longer exists. It's data portability for Local-mode users, whose
tasks otherwise exist in exactly one place with no second copy. On Play, where
most users won't have a sync engine, that's the majority.

One `.ics` per list — a list is a CalDAV collection, and that's the unit other
clients understand — written through SAF to either a folder or a single zip.
Local tasks have no `_uid` (only a sync adapter may assign one), so the writer
synthesises a stable UID per task; without it a re-imported backup would
duplicate every task instead of matching it.

---

## Sync — own adapter

**Decided:** Agendula ships its own sync. Not because DAVx5 is bad, but because
depending on it makes one external maintainer's roadmap the gate on our core
feature — the same shape of dependency the whole identity decision exists to
escape.

The two precedents diverge and the choice between them is the whole point:
tasks.org has its own authority **and its own sync** (sovereign); jtx Board has
its own authority and **depends on DAVx5** (and got added, though a working
relationship with bitfire is part of that story). We're taking the tasks.org
shape.

**Play sharpens this.** DAVx5 is a paid app on Google Play and free only on
F-Droid — *worth confirming, since it's load-bearing* — which means most Play
users will never have it. Lobbying bitfire is therefore an **F-Droid-audience
feature, not a sync strategy**.

**Still file the DAVx5 issue** — cheap, non-blocking, real value for F-Droid
users. And make it the strongest possible version of the ask: our provider *is*
the dmfs provider with renamed strings, so it's byte-identical contract
compliance and a small enum-shaped addition with near-zero ongoing maintenance
for them. Say that explicitly. "Here's a change that can't break anything" lands
very differently from "please support my app."

**The design is now written out in [`SYNC.md`](SYNC.md)** — protocol coverage,
the account model, conflict resolution, the VTODO ↔ `TaskContract` mapper, and
where the DAV/iCalendar work lives. Two corrections to what this section
originally said, both verified 2026-08-13:

- `dav4jvm` is **MPL-2.0**, not Apache-2.0. Still fine against our MIT (file-level
  copyleft), but it is ⚠️ **JitPack-only**, which collides with our
  `FAIL_ON_PROJECT_REPOS` + `google()`/`mavenCentral()` policy and with the
  JitPack dead end below. `SYNC.md` open question 1.
- `ical4android` is **superseded by `synctools`, which is GPLv3** — so it is
  unusable, and the open question below is closed. We write the mapper in-house.

---

## Permissions — only what the mode needs

The manifest is static, so "request only what we need" is really two different
mechanisms, and conflating them is how apps end up over-permissioned:

- **Runtime (dangerous) permissions** — genuinely stageable. Ask at the moment
  the feature is used, never up front.
- **Install-time (normal) permissions** — declared unconditionally; the only
  lever is **not declaring them until the feature ships**, and not letting a
  bundled dependency drag in ones we don't use.

| Permission | When |
|---|---|
| *(none)* for our own provider | same-uid access needs no grant — `ProviderStatus.NEEDS_PERMISSION` must never fire in Local/Synced mode |
| `org.dmfs.permission.*`, `org.tasks.permission.*` | requested **only** when the user selects External mode; declared always (static manifest) |
| `POST_NOTIFICATIONS` | when reminders are first enabled |
| `USE_EXACT_ALARM` / `SCHEDULE_EXACT_ALARM` | when exact due-time reminders are used. Note Play reviews `USE_EXACT_ALARM` and requires the app to be a calendar/alarm/task app — we qualify, but it needs a justification in the listing |
| `INTERNET` | **don't declare it until sync ships** |
| `GET_ACCOUNTS` | never — stripped from the vendored provider; our own account type doesn't need it to see its own accounts |

~~**Work item:** the permission gate … needs a bypass for our own provider.~~
✅ Done. `ProviderResolver.hasPermission` short-circuits to `true` when
`TaskProvider.isOwn`, so `ProviderStatus.NEEDS_PERMISSION` cannot fire in
Local/Synced mode, and `PermissionViewModel` never offers our own permissions to
the request launcher. Covered by `ProviderResolverTest`.

---

## What lands in floret-kit

Standing rule, matching the kit's own thesis (*share the mechanics, keep the
look — the kit never knows about a specific app's domain*): if it isn't
task-domain, it goes to the kit.

| Candidate | Kit module | Note |
|---|---|---|
| ContentProvider seam — `ColumnReader`, failures, observer→Flow | `core-provider` | **already on the kit's deferred list**, blocked on migrating Calendula to the name-based reader. Bundling our own provider is the forcing function that makes this worth doing. |
| Runtime-permission staging — request/state machine, rationale plumbing, "ask at point of use" | new, e.g. `core-permissions` | pure mechanics, and Calendula has the identical problem |
| DAV client + iCalendar parse/serialize | new, e.g. `core-dav` | **the big one.** Calendula is a calendar app; it needs the same primitives. Worth designing for two consumers from the start rather than extracting later |
| Export/backup plumbing — SAF, file writing, share-out | kit | the *serialization* of tasks is domain; the plumbing isn't. **Built app-local for now** (`data/export/ExportWriter`), on the kit's own principle of not extracting before a second consumer exists — the seam is in place, so moving it is a file move. `ICalendarWriter` stays app-local permanently: it's domain. |
| Sync-adapter/account scaffolding | kit, probably | the `AbstractThreadedSyncAdapter` + authenticator boilerplate is identical everywhere; the delta logic is domain |

**Stays app-local:** the vendored `:provider` module (task-specific, and
Apache-2.0 against the kit's MIT), `TaskContract` and the mappers, domain models
and smart lists, all screens, and the reminder *scheduler* (per the kit's
existing "not shared" call — Agendula pulls, Calendula pushes).

---

## Distribution — F-Droid and Play from day one

Not on either yet; both are targets, so build *for* them rather than retrofitting.

- **F-Droid** requires from-source. The in-tree `:provider` module satisfies it;
  a JitPack artifact would not. floret-kit's composite build already keeps the
  kit from-source, and the reproducibility guard (`vcsInfo { include = false }`
  in `app/build.gradle.kts`) is already in place.
- **Play** requires a rising target-API floor, a data-safety declaration, and
  justification for `USE_EXACT_ALARM`. It also means dangerous permissions we
  don't use are a liability, not just clutter — which is most of why
  `GET_ACCOUNTS` and the stray receiver come out of the vendored provider.
- **Parked, not solved:** dual-distribution signing. F-Droid reproducible builds
  verify against *our* signed APK; Play App Signing re-signs with Google's key.
  Both can coexist, but it needs a deliberate pass before the first Play upload.
  See `RELEASING.md`.

---

## Dead ends — do not revisit

- **One APK that detects at install time and adapts.** Impossible.
  `<provider>` authorities and `<permission>` declarations are frozen at build
  time and read by the OS at install; there is no install-time hook where our
  code runs. And unlike a component, a `<permission>` cannot be runtime-toggled
  — no `setComponentEnabledSetting` equivalent.
- **Dynamic feature modules** to deliver the provider conditionally. Conditions
  are limited to hardware features / SDK / country — there is no "only if app X
  is absent" — and they require Play, so they're dead for F-Droid regardless.
- **`frontend` / `standalone` build flavors.** Two flavors means two
  `applicationId`s (two listings, two signing lines, and switching costs a user
  their local data), or one `applicationId` and they can't coexist in a repo
  anyway. Obsolete now that our provider coexists with everything instead of
  replacing anything.
- **Maven Central for the provider.** `org.dmfs:opentasks-provider` *is* there —
  but only up to `1.1.8.1` (2016, `jar` packaging, 3 versions). No DB 23.
  Verified.
- **JitPack (`com.github.dmfs.opentasks:opentasks-provider:1.4.2`).** Has the
  right version, but it's a prebuilt artifact (fails F-Droid from-source), it
  can't have its hardcoded permission names renamed, and adding JitPack widens
  the dependency trust surface — `settings.gradle.kts` is currently `google()` +
  `mavenCentral()` only, under `FAIL_ON_PROJECT_REPOS`. *Still usable for a
  throwaway spike* (a library string resource can be overridden from the app
  module, so the authority rename works), but not for anything we ship.

  ⚠️ **This one comes back.** It is a dead end *for the provider*, where
  vendoring was mandatory anyway. `dav4jvm` is JitPack-only, so the sync adapter
  has to answer the same question on its own terms — and F-Droid turns out not to
  be the obstacle (its inclusion policy trusts jitpack.io for freely-licensed
  artifacts); our own trust-surface policy is. See [`SYNC.md`](SYNC.md) open
  question 1.

---

## Sequencing

1. **Merge `fix/provider-interaction-review`** (`47cf99a`, currently unmerged
   into `main`). It's blocking nothing and rotting, and it touches the exact
   permission flow step 2 changes.
2. **Vendor `:provider`** under our own authority and permission namespace, with
   the permission-gate bypass. This is the identity, done once, done right —
   and it ships a complete local-first app to both stores.
3. **Export/backup.** Now a v1 feature, not a migration hack.
4. **File the DAVx5 issue.** Non-blocking, cheap, serves F-Droid users.
5. **Sync adapter.** The 1.x arc; design discussion pending.

**Scope honesty:** the withdrawn notes costed this at "2–4 days shippable, +1
week for F-Droid." Steps 2–5 are a substantially larger program than that, and
the roadmap should say so rather than inheriting the old estimate.

---

## Open questions

1. **Sync protocol coverage**, account model, conflict resolution — ✅ taken up in
   [`SYNC.md`](SYNC.md). The account model is answered there (`AccountManager`,
   which `PROVENANCE.md` change 1 already assumes); what stays open moves to that
   document's own list — dav4jvm's distribution, conflict policy, External mode's
   future, and recurring-task completion.
2. **Resolver ordering** — ✅ decided, see
   [Storage modes](#storage-modes--the-users-choice). The **mode-selection UX**
   is still open: `autoMode()` picks a default, but the Settings override it
   assumes does not exist yet.
3. **Does the vendored provider work with no account at all?** ✅ Answered, with
   a caveat about *how* it was answered.

   By construction: `cleanUpLists` exempts local lists explicitly (upstream's own
   rule), and our rework restricts pruning to account types this package
   authenticates — currently none — so nothing can be pruned at all.
   `ProviderAccountCleanupTest` creates a local list and a task in it with zero
   accounts present and reads both back.

   ⚠️ **But that test is Robolectric, and it skips on ARM64**, where Robolectric
   has no SQLite backend in either mode. It runs on x86_64 CI. It is not a
   substitute for a device, and this remains on the device-verification list.
4. ~~**`ical4android` licensing** vs our MIT.~~ ✅ Closed: `ical4android` is
   superseded by `synctools`, which is **GPLv3**, so it is out — as is
   `cert4android`. The export path never depended on it anyway (`ICalendarWriter`
   is our own ~200 lines). The sync adapter's iCalendar parsing goes through an
   in-house mapper over `ical4j`/`biweekly`; see [`SYNC.md`](SYNC.md).
5. **jtx Board** as an additional External-mode candidate — richer contract,
   later. (`PLAN.md` decision #3, still open.)
6. **The vendored provider's timezone-change behaviour** — upstream's receiver
   has a comment describing `break`s that were never written. We preserved the
   observed behaviour and wrote it out explicitly; which of code or comment is the
   bug wants a device to settle. Change 3 in
   [`provider/PROVENANCE.md`](../provider/PROVENANCE.md).

---

## Related

The provider-interaction review on `fix/provider-interaction-review` fixed,
among others: recurrence-aware editing (routes through the instances URI),
all-day UTC handling, the `DUE`/`DURATION` collision, per-task reminders (Alarm
property rows), and flow-recovery robustness. That makes `ROADMAP.md` open
decision #5 ("recurrence-aware editing out of scope for v1") **stale**.