agendula/docs/SYNC-PLAN.md

Agendula — CalDAV sync: the build plan

Branch: feat/caldav-sync, cut from release/v1.0.0. Design: SYNC.md — the decisions, the traps and the audit trail behind them. This document does not repeat it. It sequences it. Shape: five chunks, one branch, one PR at the end.

SYNC.md is a 1,200-line decision document with roughly forty ⚠️ findings scattered through it, most of which are "the obvious implementation is wrong, here is why". That is the right shape for a design document and the wrong shape for a work queue. This is the work queue.

---

Decisions taken before the first line of code

SYNC.md left three questions open and named two of them as blocking. All three are now answered, plus one the phases imply. These are not reopened by the implementation chunks — if a chunk finds evidence that overturns one, it stops and says so rather than quietly picking the other branch.

#	Question	Answer	Consequence
1	dav4jvm + cert4android distribution, and the Java-21 wall	Vendor a known-good tree, recompiled at our Java 17 target	FAIL_ON_PROJECT_REPOS stays; no Ktor/guava/xpp3 tail; MPL-2.0 headers retained and the attribution screen becomes mandatory, not optional. Freezes the API churn that shipped two breaking majors nineteen days apart
2	Conflict policy on 412	Server wins, local edit discarded	DAVx5's policy. Terminates, always. The discarded edit is surfaced — a sync report the user can read — because silence is what makes this policy feel like data loss. The draft's "preserve as a duplicate" stays withdrawn: RFC 4791 §4.1 makes it unuploadable
3	External mode's future	Kept, unchanged	The mapper and the UI stay dual-capable. Retiring it is a separate decision that does not block sync, and it ships and works today
4	iCalendar library	None — a hand-rolled content-line model. ⚠️ Overturned during chunk 1; SYNC.md § Libraries assumed a typed library was the only option	A raw (name, params, value) content-line tree is what the unknown-property requirement actually wants: a typed model normalises away exactly what must survive. ICalendarWriter already folds in 204 lines, lib-recur is already a direct :app dependency and does RRULE, and java.time is native at minSdk 29 — so ical4j's 2.2 MB of duplicated zone data, its production-exhausting ZoneRulesProvider, its mandatory properties/cache/registry shims and its release-only R8 failure buy nothing. VTIMEZONE bodies are already on the round-trip allowlist, so they round-trip opaquely. Cost accepted: we own the lexer. biweekly was rejected on the same ground as before

---

Scope boundaries

Not in this branch, deliberately:

• Extraction into floret-kit. SYNC.md § What lands in floret-kit is right that core-dav and core-sync belong there and that Calendula needs the same primitives. Extracting across a submodule boundary while the API is still moving costs more than it buys. Mitigation, which is a real constraint on every chunk: the DAV and iCalendar layers take no task-domain type and no Android UI type, so the later extraction is a file move. Chunk 5 records what moves.
• Retiring External mode, per decision 3.
• A release. Nothing here bumps versionCode / versionName. Sync ships when it works against real servers, and that is a decision taken after the device review, not inside this plan.

In scope but not verifiable by CI: everything that needs a real server. The per-server trap matrix (SYNC.md § Server reality) is written as named, skipped integration tests in chunks 3–4 and turned on by hand against a live Nextcloud/Radicale/Baïkal in chunk 5.

---

The five chunks

#	Chunk	Rests on	The thing it must not get wrong
1	Mapper — VTODO ↔ Room	nothing	Unknown properties survive a read-modify-write cycle
2a	Vendored DAV foundation	nothing	Vendor a tree we can actually maintain, and know which of its defects are real
2b	Discovery and auth protocol	2a	The two collection filters are inversions of the obvious rule
2c	The Android account layer	2b	Registering the sync adapter, or every ContentResolver sync call is a silent no-op
2d	Account-add UI	2c	Never send a credential into an unvalidated redirect chain
3	Engine core — read, write, conflicts	1, 2	A failed resource must not fail the collection
4	Incremental sync + scheduling	3	Never persist a sync token before the bodies it covers are applied
5	Hardening, compliance, real servers	1–4	Ship no licence violation, and no retry loop on a dead app password

Chunks 1 and 2 are genuinely independent of each other; the ordering between them is arbitrary and 1 goes first only because it is the one with a specification that can be written down before any network exists.

---

Chunk 1 — the mapper

Goal: a bidirectional VTODO ↔ Room-entity mapper whose specification is its fixture corpus. Today ICalendarWriter is the export half only — write-only, hand-rolled, and it silently drops everything it does not model.

The corpus comes first. Not as a testing courtesy: SYNC.md § Unknown properties is explicit that the fixtures that catch bugs are the adversarial ones, and a mapper written before its corpus gets a corpus that ratifies it. Minimum set, each one a named failure the design predicts:

• a CLASS:CONFIDENTIAL task as Nextcloud rewrites it out of a shared calendar — the one that destroys data on write-back
• a master plus RECURRENCE-ID overrides in one resource
• unknown properties nested inside a VALARM — the case a flat property-per-row model cannot represent
• an entirely unknown sub-component
• a TZID the device tzdb does not know
• a UID containing / and @
• one exceeding CALDAV:max-resource-size
• RRULE + DUE with no DTSTART, which has no well-defined RECURRENCE-ID
• X-MOZ-LASTACK / X-MOZ-SNOOZE-TIME (dropping them causes Thunderbird alarm storms) and X-APPLE-SORT-ORDER
• all four recurring-completion models on read (a/b/c/d — we write (a))

Round-trip assertion, stated the way SYNC.md corrects it. Byte-stability is unachievable and asserting it produces a corpus that gets normalised until it tests nothing. Re-parse both sides into a canonical multiset of (component path, property name, params as a sorted map, unfolded unescaped value) and assert equality modulo an enumerated allowlist: PRODID, DTSTAMP, LAST-MODIFIED, SEQUENCE, VTIMEZONE bodies, fold positions, parameter quoting. Byte-equality is asserted where it means something — the unfolded, unescaped value octets of every untouched property, and full parameter preservation including unknown parameters.

Storage for the unknown half. A new table, and therefore a schema migration to v2 with an exported schema and a MigrationTestHelper test, per the repo's existing pattern in app/schemas/. It must represent nesting (component path), ordering, and opaque unknown sub-components. Cap the total at ~25 kB per resource, as DAVx5 does, for CursorWindow and CALDAV:max-resource-size both.

Deliverables

• fixture corpus under app/src/test/resources/vtodo/, with a README naming what each fixture is for
• VTodoParser / VTodoSerialiser behind one interface, no Android types
• unknown-property table, Room migration v1→v2, migration test
• the SYNC.md § The rest of the minefield rules as individual tests: SEQUENCE is preserve-verbatim; DTSTAMP regenerates but LAST-MODIFIED does not; COMPLETED is UTC-only; RELATED-TO;RELTYPE=PARENT points up; PRIORITY 0 = undefined; a TRIGGER;RELATED=END alarm without DUE is invalid and must be caught before PUT, because ordinary UI actions reach it
• ICalendarWriter either becomes the serialiser or is deleted in its favour — two VTODO writers in one app is the defect this chunk exists to prevent
• ical4j's ical4j.properties, MapTimeZoneCache and registry shim, plus its R8 keep rules (-keep class net.fortuna.ical4j.** { *; } + the -dontwarn set), because that failure is release-only

Also settle here: the VALARM ownership collision. Either the adapter owns alarms and AndroidTasksDataSource.setAlarm stops bulk-deleting property rows, or reminders stay local-only and are never serialised. Picking neither is how one local reminder edit destroys every server-side alarm on that task.

Done when: the corpus round-trips, the migration test passes both directions, and no fixture loses an unknown property.

Settled while building it

• ⚠️ No schema migration was needed. TaskEntity.unknown_properties already exists at v1, reserved for exactly this and written by nothing. The residue fills it. It holds leftover properties followed by whole sub-component blocks — BEGIN/END lines are content lines like any other, so nesting and unknown sub-components fall out of the same representation, which is what the plan thought needed a second table.
• VALARM ownership: neither side writes the other's alarms. VALARMs round-trip in the residue and are never authored; local reminders live in task_alarms and are never serialised. The collision SYNC.md describes was AndroidTasksDataSource.setAlarm bulk-deleting provider property rows — in the own-store world the two stores are disjoint and neither can destroy the other. Merging them is a later decision; the point is that it is now a decision, not an accident.
• The mapper claims a property only when it can reproduce it exactly. Everything else stays in the residue: a value it cannot parse or that is out of range (PRIORITY:11, PERCENT-COMPLETE:150, SEQUENCE:x, STATUS:X-DEFERRED), a time it can read but not reproduce (floating, or a TZID this device's tzdb lacks), and a DTSTART/DUE pair that disagrees on value type or timezone — one is_all_day flag and one timezone column cannot author both, and flattening the odd one out destroys it. Clamping or defaulting any of these would be a silent rewrite of somebody's data. SUPPRESSED_BY_RESIDUE makes "present in the residue" mean "do not author this".
• ⚠️ Suppression is conditional, or editing breaks. A residue property suppresses its column only while the two still agree. If the user edits a field whose stamp was unreproducible, the stale residue copy is evicted and the column is authored — otherwise changing the due date of an imported task would silently do nothing on the server. RELATED-TO is the deliberate exception: a parent we have not fetched is not the same as no parent, so an unresolvable link is kept rather than destroyed.
• One normalisation is allowed beyond the stated allowlist, and it is an equivalence rather than a concession: an absent STATUS and STATUS:NEEDS-ACTION mean the same thing for a to-do. Any other STATUS compares exactly, so losing a completion still fails the corpus.

---

Chunk 2a — the vendored DAV foundation

⚠️ Split out of chunk 2 while building it. Vendoring is a self-contained piece with its own verification — upstream's suite has to pass unmodified before anything is built on top — and bundling it with discovery and auth would have produced one commit nobody could review.

Version: dav4jvm 2.2.1, the last OkHttp release. 3.0.0 deleted the OkHttp package for Ktor and 4.x requires Java 21, and SYNC.md's entire auth section is written in OkHttp terms — preemptive Basic via an Interceptor, OkHttp stripping Authorization on cross-host redirects, BasicDigestAuthHandler because OkHttp has no Digest. Taking 4.x would have invalidated all of it. A plain JVM module, not an Android library: the tree has zero Android imports and must keep it that way, or the floret-kit extraction stops being a file move.

Full record in dav/PROVENANCE.md. Of the two defects SYNC.md said we would inherit, one was not real — 2.2.1 does follow 303 — and the other (dav4jvm#209, permanent redirects never reaching the caller) is fixed. A third, which the audit did not have, was found by writing the tests upstream never wrote: HTTP dates were parsed and formatted in the device's local zone, putting every getlastmodified out by the local UTC offset.

Done when: upstream's 63 tests pass unmodified, commons-lang3 and the xpp3 runtime dependency are gone, and :app links against the module.

---

Chunk 2b — the discovery and auth protocol

⚠️ Split again while building it. The seam is the platform: everything here is protocol, testable on a JVM against MockWebServer, and none of it touches Android. Keystore, AccountManager, Custom Tabs and the account-add UI are a different kind of work with a different kind of verification — including the on-device review — so they are chunk 2c.

Lands in a new :caldav module: MIT, plain JVM, api-depending on :dav. A separate module from the vendored MPL tree keeps the licences unmixed and makes "no Android types" a compile-time guarantee rather than a discipline.

One dependency added: dnsjava 3.6.3 (BSD-3) for the SRV/TXT half of RFC 6764. Android's own DnsResolver is callback-only and cannot do the TXT path= lookup, and JNDI's DNS provider does not exist on Android at all. It is what DAVx5 uses. Behind a DnsResolver interface so the pipeline is testable without a network.

Done when: the trap table is executable — Posteo's SRV-only 8443, GMX's TXT path=, null SRV targets, Google's dead-end record, SOGo's triple resourcetype, Nextcloud's trashed calendar, the absent/empty component set, and <D:unauthenticated/> as a 200 that means failure.

---

Chunk 2c — the Android account layer

Everything that needs the platform and nothing that needs a screen: Keystore credentials, AccountManager, the stub sync adapter, the manifest, and the network security config. The account-add UI is 2d — it is a design task, it needs the material-3 skill, and it is the piece that needs an on-device review.

⚠️ A stub ContentProvider turned out to be required

Not in the original plan, and it is load-bearing. A sync adapter registers against a content authority, and Agendula publishes no provider — :provider was deleted when we took our own Room store. With no authority there is nothing for <sync-adapter android:contentAuthority> to name, nothing for requestSync to address, and nothing for Settings to render a switch against. SyncStubProvider stores nothing and exists solely to hold up that end.

Other things settled here

• The account type and authority are per build variant, generated by resValue. Two installs cannot own the same account type, so a debug build sharing the release build's would fight it. SyncContractTest asserts the Kotlin constants and the generated strings still agree — drift between them is invisible at build time and surfaces as an account the framework will not trigger.
• The credential blob is the one thing excluded from backup. It lives in its own DataStore file for exactly that reason. Keystore keys are non-exportable, so a restored ciphertext is permanently undecryptable; excluding it means the user signs in again, which is the honest outcome. Excluding the database or all of DataStore would trade a latent bug for a live one.
• ⚠️ The network security config trusts the whole user CA store, for all traffic. SYNC.md specifies it, and without it a correctly installed private CA is not trusted at all — which is the self-hosting case. But base-config is the widest form: any CA in the user store can intercept the CalDAV connection and read the app password from the Authorization header. Chunk 5's cert4android should replace this block, not sit beside it — its per-connection approval is the narrow version of the same capability.
• FOREGROUND_SERVICE appears in the merged manifest without being declared, from work-runtime. That is not the FGS route: below API 31 WorkManager implements expedited work with a foreground service, and minSdk is 29. Noted in the manifest because it shows in F-Droid's permission diff.

Not run: the instrumented tests here (CredentialStoreTest, SyncContractTest) compile but have not been executed — CLAUDE.md reserves device interaction for when it is explicitly asked for. They need a device run before chunk 2 is done.

---

Chunk 2d — the account-add UI

One flow, one back-stack entry, as a stepper rather than four destinations — the steps are not independently reachable, and "back" from the browser step means abandoning a server-side flow rather than popping a screen. It hangs off Settings using the same sliding-section pattern Storage → Export already uses.

⚠️ PreemptiveBasicInterceptor was deleted here, not kept. The vendored BasicDigestAuthHandler already sends Basic preemptively over HTTPS, and it also does Digest (Baïkal defaults to it and OkHttp has none), caches which scheme worked, and restricts by registrable domain rather than exact host — which is what a cross-host home set needs, since iCloud puts the principal on caldav.icloud.com and the home set on pNN-caldav.icloud.com. Shipping two implementations of preemptive Basic is the same defect chunk 1 removed when ICalendarWriter stopped carrying its own folding.

A seam was added for testability, after the review found eight issues in one untested ViewModel. CalDavGateway and AccountCreator put the network and the database behind interfaces, so the sign-in state machine — which decides where five discovery outcomes lead, when a one-shot app password is spent, and which host a credential is scoped to — is exercised without a server, a database, a Keystore or an AccountManager.

Still open, and small: the system entry point (Settings → Accounts → Add account → Agendula) refuses with a message pointing at the in-app flow rather than driving it. Wiring it means MainActivity handling SyncAuthenticator.ACTION_ADD_ACCOUNT and answering the AccountAuthenticatorResponse.

Done when: the flow has had an on-device review and an explicit go-ahead — CLAUDE.md's rule, and this is the case it exists for.

---

Chunk 2d — the account-add UI (original outline)

Goal: the app can add a CalDAV account and list its VTODO collections. No syncing yet.

Vendoring, first. A new Gradle module holding dav4jvm + cert4android sources at our Java 17 target, MPL-2.0 headers intact, with a PROVENANCE.md recording the upstream commit — the repo already has this pattern from :provider. Fix the two inherited defects while vendoring, since we now can: 303 is not handled (RFC 6764 §5 names it explicitly) and issue #209 mutates location in place so permanent redirects never reach the caller.

Discovery is the nine-step pipeline in SYNC.md § Generic CalDAV discovery, including every step marked ⚠️ MISSING there. The two filter corrections are the important part and both are inversions of the obvious:

• supported-calendar-component-set absent means "supports everything." Request properties by name — RFC 4791 §5.2.3 says the property SHOULD NOT come back from an allprop request. Treat empty as all.
• Classify on resourcetype as an unordered set, with a positive test for CALDAV:calendar — not by excluding schedule-outbox, because SOGo's main personal calendar reports collection + calendar + schedule-outbox simultaneously for every non-Apple client, which is exactly what we are.

The discovery traps table (Posteo SRV-only on 8443, GMX/Web.de path=, null SRV target, Google's dead-end SRV, iCloud/Zoho well-known 401, dav.runbox.com's HTTPS→HTTP downgrade, <D:unauthenticated/> as a 200 that means failure, cross-host home sets) becomes a table-driven unit test over recorded responses.

Nextcloud Login Flow v2 with all five corrections: POST form-encoded (a GET is 405); an explicit User-Agent, because it becomes the app password's name in the user's security settings and okhttp/4.12.0 defeats the entire point of the flow; 404 means pending only and anything that is neither 404 nor 200 stops the poll; validate the endpoint origin and refuse an http downgrade outright; and loginName is not the uid — it is the Basic auth username and nothing else. Custom Tabs needs the <queries> entry, the ACTION_VIEW fallback, {token, endpoint, deadline} persisted before launch, and an explicit "I finished / Cancel" affordance.

Auth is not just Basic. Digest (Baïkal defaults to it, OkHttp has none), Basic sent preemptively via an Interceptor gated to HTTPS and the account's own origin, and domain-detection at account-add time for the three servers whose real error is not "wrong password": Fastmail (app password; Basic plan has no CalDAV), iCloud (app-specific password, 2FA to mint one), Google (OAuth2-only — refuse with an explanation, SYNC.md drops it as a target).

Credentials: Keystore AES/GCM/NoPadding, blob in DataStore. Do not call setUserAuthenticationRequired; do not set setUnlockedDeviceRequired (breaks background sync). AEADBadTagException and KeyPermanentlyInvalidatedException mean re-authenticate, not crash. Exclude the blob — and only the blob — from Auto Backup: a restored ciphertext is permanently undecryptable.

The account plumbing, which is the part that silently does nothing if skipped. AccountManager plus a registered AbstractThreadedSyncAdapter whose onPerformSync enqueues a WorkManager job and waits. Without a registered adapter, hasAuthorityAccess() makes every ContentResolver sync API a silent no-op at targetSdk ≥ 34 — no exception, no log, and it passes on a Robolectric shadow. Manifest: INTERNET, READ_SYNC_SETTINGS, WRITE_SYNC_SETTINGS, ACCESS_NETWORK_STATE; the authenticator <service> exported and guarded by android.permission.ACCOUNT_MANAGER (ACCOUNT_AUTHENTICATOR does not exist). Ship an in-app sync button, since "Sync now" stays greyed out under userVisible="false". Add androidx.work, androidx.hilt:hilt-work and androidx.browser to the catalogue, with the HiltWorkerFactory, the removed default WorkManagerInitializer and an @EarlyEntryPoint for the authenticator.

Also: ship a network-security-config with <certificates src="user"/>, or a user who correctly installs their private CA is still not trusted.

UI in this chunk needs on-device review before it can be called done — the account-add flow is the first screen a self-hoster meets, and per CLAUDE.md nothing UI-facing gets tagged before that review.

Done when: an account can be added against a real Nextcloud and its task lists appear, the account shows in system Settings with a working sync switch, and the discovery trap table is green.

---

Chunk 3 — engine core

Goal: a full bidirectional sync that is correct but not yet clever — no sync-collection, no scheduling beyond a manual trigger.

Read path. REPORT calendar-query with a VTODO comp-filter and no time-range, matching DAVx5 — which deliberately does not use RFC 6578 for tasks, and omits the time-range because some servers return no tasks without a time at all. Then calendar-multiget in batches, matching returned hrefs against what was asked for, because real servers reply with responses for unrelated URLs. Never request calendar-data inside a REPORT that is not sanctioned to carry it.

Write path. If-None-Match: * on create, If-Match on update and DELETE. Send Prefer: handling=strict to sabre-based servers — the cheapest single fix in the whole audit, because it preserves both our bytes and the ETag. Request Accept-Encoding: identity. Strip W/ and keep a weak flag; if a PUT returns no ETag or a weak one, discard it and re-fetch.

412 means three different things and they get three code paths: on create it means the filename is taken (re-fetch, adopt if the UID matches, else regenerate as a UUID); on update it means the server is newer (decision 2: server wins, report the discard); on update where the resource is gone it is spec-correct and not a conflict at all (HEAD to disambiguate — 404 is delete-vs-edit).

Never write back a body whose ETag does not match the hash of what we downloaded. This is the Nextcloud shared-calendar landmine and it is the single most destructive bug available in this chunk: CalendarObject::get() strips VALARM on read-only shares and reduces CLASS:CONFIDENTIAL to a VEVENT-shaped whitelist that deletes DUE, STATUS, COMPLETED, PERCENT-COMPLETE, PRIORITY and RELATED-TO — while leaving the ETag untouched.

Isolation, in two layers. A failed collection must not fail the account, and — its twin, which the draft omitted — a failed resource must not fail the collection. Per-resource quarantine with a failure counter, not backoff: a single HTTP 400 has halted all calendar sync in DAVx5 for weeks. 507 MUST NOT be auto-retried (RFC 4918 §11.5), and 5xx is not safely retryable either — a contradictory RRULE/EXDATE pair returns 500 from Nextcloud and will do so forever.

Client-side validation before PUT, because sabre returns 415 for things ordinary UI actions produce: DUE before DTSTART, value-type mismatch between them, a present METHOD, multiple UIDs, mixed component types in one resource.

href ≠ UID. Sanitise filenames on vdirsyncer's rule — a–zA–Z0–9_.-+, excluding @ — cap the basename near 200 bytes, fall back to a UUID. DELETE: conditional on If-Match, 404/410 count as success, and a locally deleted resource that was never uploaded is never DELETEd.

Local change detection is is_dirty = 1 OR is_deleted = 1 scoped by list — the columns already exist in the v1 schema. Every downstream insert writes is_dirty = 0 explicitly.

Done when: a task created in Nextcloud web appears locally and vice versa; a concurrent edit resolves server-wins with a visible report; a quarantined resource does not stop its collection.

Settled while building it

⚠️ The mapper emitted TZID with nothing to resolve it. Chunk 1 writes DTSTART;TZID=Europe/Berlin:…, and RFC 5545 §3.2.19 requires a TZID without a leading solidus to reference a VTIMEZONE in the same object. Nothing generated one — VTIMEZONE sits at VCALENDAR level, outside the VTODO whose residue the mapper stores, so it was outside the round-trip guarantee entirely. Left alone, every zoned task would have been malformed, and Prefer: handling=strict — which chunk 3 sends precisely so servers stop repairing our bytes — turns malformed into rejected. VTimeZones now generates the definition from java.time's own rules, which also keeps the zone we write in agreement with the zone we compute occurrences in. Cost accepted: only the currently effective rules are emitted, not the historical transition table. Tasks are dated now or later.

java.time does not encode "the last Sunday" as -1. It arrives as dayOfMonthIndicator = 25 — "the first Sunday on or after the 25th" — and only the fact that a seven-day window ending on the last day of the month is the last occurrence identifies it. The obvious -1 test never fires for any European zone, and the fallback emits a seven-value BYMONTHDAY list where every other client writes BYDAY=-1SU.

GetETag.eTag has already been parsed. dav4jvm strips the W/ marker and records it in a separate field, so feeding its value back through an ETag parser reports every weak tag as strong — the exact failure the weak flag exists to prevent. ETag.from(property) and ETag.parse(header) are now different functions for that reason, and a test pins the difference.

The discard is reported when the replacement arrives, not when the 412 does. Announcing it at the conflict — and clearing is_dirty there — makes the loss real if the replacement download then fails, with nothing left to retry. The row now stays dirty until the download overwrites it.

A SyncStore seam, not Robolectric. The reconciliation is where local edits are discarded, tombstones swept and conflicts resolved; proving that needs a test double for eight methods, not an in-memory Room plus a new test runtime.

The mutilation guard is scoped to what is actually reachable. Nextcloud reduces CLASS:CONFIDENTIAL objects served from a share while leaving the ETag intact; VALARM stripping happens on read-only shares, which are never written to anyway. So the refusal is: shared collection + confidential + already on the server. The collection's read-only and shared flags are re-read on every sync rather than trusted from account-add, because ACL churn is silent.

Manual trigger. ContentResolver.requestSync is gated behind hasAuthorityAccess() at our targetSdk and returns silently when it refuses, so the in-app button enqueues the WorkManager job directly via SyncTrigger. The sync adapter uses the same path.

Found by the review, and worth naming

⚠️ An empty listing would have hard-deleted the whole list. The sweep took "absent from remote.list()" as proof of a server-side delete, and its evidence is a calendar-query with a VTODO comp-filter — the filter whose mishandling is the reason the query carries no time-range in the first place. A server answering it with an empty successful multistatus is indistinguishable from an empty collection, and one such answer destroyed every task in that list in one pass. An empty listing now never sweeps. Cost accepted: a collection genuinely emptied on the server keeps its local rows until one task reappears there. That is recoverable by hand; the other error is not.

Quarantine did not cover creates. Failures on a resource with no href yet were counted under its UID and read back under its href, so nothing ever read them: a new task the server rejects permanently was re-PUT on every sync forever — the exact DAVx5 failure the counter exists to prevent — while the unread keys grew in DataStore without bound. Resources are now keyed by href or uid:…, and a success clears both.

A RELATED-TO deleted on the server never unparented anything. Only present parents were recorded, and upsert carried the old parent_id forward — which the writer then resolved straight back into a RELATED-TO, re-uploading the link the user had deleted elsewhere.

Two validators disagreed about what a DATE is. ResourceValidator tested only VALUE=DATE while the mapper also reads a bare eight-digit value as one, so a residue DTSTART:20260101 beside an authored DUE;VALUE=DATE:20260102 was rejected locally and never left the device — a case VTodoMapperTest already had a test for. The per-component rules now delegate to VTodoMapper.validate, which also restores the TRIGGER;RELATED=END check that the new validator had silently dropped and left as dead code.

An unresolvable TZID produced a resource with no definition for it. A Windows zone name from another client survives in the residue, and java.time cannot regenerate a VTIMEZONE for it — so with Prefer: handling=strict the upload becomes an unexplained rejection. It is now refused by name. Open for chunk 5: preserving the server's own VCALENDAR-level VTIMEZONE would fix it properly, and needs somewhere to put residue that is not the VTODO's.

Three narrower ones, all fixed: quarantine counts were a global read-modify-write, so two accounts syncing at once discarded each other's (now merged inside edit); NeedsSignIn and Misconfigured never called recordSync, leaving the accounts screen reporting "synced 5 minutes ago" for an account that cannot sync at all; and apply() re-read every row in the list once per downloaded resource.

---

Chunk 4 — incremental sync and scheduling

Goal: sync-collection as the optimisation on top of chunk 3's baseline, and sync that runs by itself.

Every numbered finding in SYNC.md § RFC 6578 is a test in this chunk. The four that are not optional:

1. Invalidation has no status code. Ignore the status; match <D:valid-sync-token/> anywhere in the body on any 4xx. Observed in the wild: 403 (sabre), 400 (Google), 409 (Radicale), 412 (Evolution accepts it). Thunderbird accepts only 400 and therefore never recovers from the 403 most of the self-hosted world emits.
2. Initial sync must not report deletions, so mark-and-sweep is mandatory and initialIncomplete must be persisted atomically with the token — otherwise a resumed partial sync sweeps against an incomplete set and deletes live data.
3. Persist the token only after the bodies are applied, per page. The RFC's own Appendix B has this backwards. Under WorkManager, process death mid-sync is routine.
4. A token the server accepts over a change log it already pruned returns 207, zero changes, and no error. RFC 6578 gives no signal for it. The only mitigation is periodic full reconciliation (PROPFIND Depth: 1 + ETag diff) on a slow cadence regardless of the token — so chunk 3's full path is a permanent safety net, not a fallback.

Plus: no DAV:limit (Nextcloud regressed it to a localised HTML error page); 507 on the SELF href is truncation, 507 as the outer status means retry without the limit; an iteration cap and a no-progress guard, because the RFC never requires the token to advance; tokens are opaque and never reused across collections, keyed (accountId, collectionUrl); deletion is <D:status>404</D:status> at <D:response> level, not inside a propstat; a 207 with no <D:sync-token> degrades to PROPFIND rather than throwing; and sync-collection never reports collection property changes, so displayname, colour and read-only status refresh only via PROPFIND on the home set.

Three membership edge cases that each look like a bug: create-then-delete between syncs is reported as removed (the delete handler no-ops on an unseen href); delete-then-recreate at the same URI is reported as changed (re-read the UID from the body); and ACL churn may be reported as removal, so apply a sanity threshold before acting on a large delete batch.

Scheduling has a ceiling. Make sync chunked and resumable — persist the cursor per collection so a killed worker resumes rather than restarts. Periodic sync is a plain PeriodicWorkRequest, no foreground service. "Sync now" from a visible screen uses setExpedited(RUN_AS_NON_EXPEDITED_WORK_REQUEST), and getForegroundInfo is implemented unconditionally — omitting it crashes below API 31 and we support 29. Android 15 forbids starting a dataSync FGS from BOOT_COMPLETED, and we have a boot receiver. Sync hard on app open and on connectivity-regained, and be honest in the UI about cadence: in the rare and restricted buckets network access is off entirely and the worst case is genuinely "once overnight".

Done when: a token invalidation on any of the four status codes recovers; a process kill mid-page loses nothing and duplicates nothing; the periodic worker runs and the manual trigger is instant.

Settled while building it

initialIncomplete turned out not to need a column — or to exist. The plan called for it to be persisted atomically with the token, to stop a resumed partial sync sweeping against an incomplete set. But the mark-and-sweep it protects is chunk 3's full path, so the rule that removes the whole hazard is simpler: a token is adopted only when a full reconciliation completes. A run killed part-way stores no token and the next one starts over. No second column, nothing to write atomically with anything.

The token is taken from the PROPFIND that precedes the read, not after it. Both are imprecise; only one is imprecise safely. A token minted after the listing silently swallows everything that changed while we were reading it; one minted before merely re-reports those changes next time, and a re-report costs an ETag comparison.

Where the cadence clock lives. task_lists.sync_token is domain state and stays in Room. "When did this collection last reconcile in full" is scheduling bookkeeping, so it is in DataStore (SyncCadenceStore) — and deliberately outside any backup, because a restored "checked recently" on a fresh install is exactly the stale trust the full path exists to break.

⚠️ ForegroundInfo must carry no foregroundServiceType. Implementing getForegroundInfo is mandatory — setExpedited falls back to a foreground service below API 31 and the default implementation throws, so a worker without it crashes on every API 29/30 device. But passing FOREGROUND_SERVICE_TYPE_DATA_SYNC re-introduces the entire tail the design rejected: the FOREGROUND_SERVICE_DATA_SYNC permission, Android 15's six-hours-per-24 budget with its fatal RemoteServiceException, and a Play video demo per declared type. Lint caught it, correctly. The type is unnecessary anyway: above API 30 setExpedited uses an expedited job and never calls getForegroundInfo, and types only became mandatory at API 34.

No boot receiver for sync. WorkManager restores its own schedule across a reboot, and Android 15 forbids starting a dataSync FGS from BOOT_COMPLETED — so a design that needed one would have had no way to run. App open calls rescheduleAll() instead, which is idempotent under KEEP and repairs the one case WorkManager cannot: a schedule lost to "clear app data" or to a restore.

Expedited is spent on the button and nowhere else. The quota is per-app and exhaustible; a background trigger that spends it leaves none for the trigger the user is actually watching.

Found by the review, and worth naming

⚠️ The cadence clock was in the backed-up DataStore — while its own KDoc, and this document, claimed it was not. Auto Backup includes datastore/, and only agendula_credentials was excluded. Restored onto a new device it would say "reconciled minutes ago", so the restored sync token would be trusted for another day: exactly the silently pruned change log the full path exists to catch. Both sync-state stores now live in their own agendula_sync_state file, excluded alongside the credentials — a restored quarantine count is the same class of lie, silently skipping resources that were never tried on this device.

The incremental download path had no write-phase guard. downloadPhase skips a row that is still dirty; downloadChanged did not. A share demoted to read-only leaves the upload refused and the row dirty, and the next change-log entry for it overwrote the user's unsent edit with no DiscardedEdit at all. The guard cannot simply be copied, either — the 412 path deliberately leaves the row dirty and waits for the download — so it is "dirty and not awaiting a refetch".

A change log describes the past, and applyRemovals treated it as the present. An entry predating this run's own upload deleted the row we had just written, leaving an orphan on the server and nothing on the device. It now respects touched, and reports a lost edit the way the sweep does.

An abandoned incremental attempt poisoned a successful run. ChangeSet.Failed and the mass-removal refusal both set report.failure, which the full fallback never cleared — so a server answering sync-collection with a bare 400 refused the new token, skipped the cadence record, and showed "last sync didn't finish" on every other sync while nothing was wrong with the data. A fallback that succeeds now demotes the attempt to incrementalNote.

refetch was silently dropped on a successful incremental run, so a PUT accepted without a strong ETag never got its canonical body back on a server that does not echo our own writes into its change log.

Two of my own patches were wrong in ways the compiler could not see. fatal() was written with its KDoc and never called — a python patch aborted on its second assertion after the first had already matched, so nothing was written, and the function sat there describing a bug it was not preventing. And the delete-then-recreate lookup read the href index after the same index had been re-pointed at the rows just written, so it never found the displaced row. The first was caught by the review, the second by a test.

Two smaller ones: the displaced lookup reintroduced the per-resource full-table scan the comment twelve lines above it forbids, and MainActivity re-ran the app-open sync on every rotation, theme switch and locale change.

---

Chunk 5 — hardening, compliance, real servers

Goal: the things that are not features and are not optional.

The server matrix, turned on. Nextcloud, Radicale, Baïkal (on Digest), SOGo, Fastmail, iCloud — each per-server trap from SYNC.md § Server reality as a named test. Two must be explicit because both silently destroy data: round-tripping a task from a shared Nextcloud calendar, and an ETag-unchanged body change on SOGo (its ETag is a row-version counter and the body is regenerated per principal). Also: Nextcloud's per-calendar UID uniqueness (409 no-uid-conflict), its trashbin renaming hrefs to <name>-deleted.ics so delete→recreate→delete returns 403, MKCALENDAR rate-limited 10/hour; SOGo never invalidating a token and using second-granularity ones; Radicale never enforcing supported-calendar-component-set. Feature-detect collection creation via OPTIONS and disable the "new task list" UI where neither MKCALENDAR nor extended MKCOL exists (iCloud is MKCOL-only, Google has neither, Posteo disables it).

Revocation, both directions. On 401: stop that account immediately, mark NEEDS_REAUTH, notify with a deep link into the login flow, and do not retry on a timer — Nextcloud's brute-force protection throttles then 429s per source IP, so a retry loop on a dead app password takes down the user's other Nextcloud clients and looks like we broke their server. Distinguish 401 from 403 from 429/503 (honour Retry-After). On account removal: best-effort DELETE /ocs/v2.php/core/apppassword with OCS-APIRequest: true, or uninstalling never revokes access.

The backup path, which arms itself the day this ships. Post-restore reconciliation must offer to re-attach the account, never prune. Pruning is event-driven off AccountManager's account-removed broadcast, not off "absent from the visible set". Device-verify by restoring onto a fresh device and confirming nothing is deleted — SYNC.md is explicit that excluding the database from backup is the wrong fix, because Auto Backup is currently Local mode's only safety net.

Licence attribution — a plain violation until it exists. MPL-2.0 §3.2(a) (dav4jvm, cert4android) requires telling recipients how to obtain source; §3.4 requires retaining file headers; BSD-3 (ical4j) requires reproducing the copyright notice in binary distributions; Apache-2.0 §4(d) propagates NOTICE. Settings exposes only our own MIT LICENSE today. Note ical4j's POM declares a non-SPDX licence name and a LICENSE URL that 404s, so generators produce empty output — this one is written by hand.

Play compliance. A privacy policy, linked in Console and in the app. File as Collected, not Shared, encrypted in transit — "not collected" is not defensible, because Play defines collection as transmitting off-device irrespective of recipient. Ship a "Remove account and delete local data" action even though the Account Deletion policy does not apply. Do not ship REQUEST_IGNORE_BATTERY_OPTIMIZATIONS in the Play build — generic server sync is not on the acceptable-use list; use ACTION_IGNORE_BATTERY_OPTIMIZATION_SETTINGS.

Minified build. :app runs R8 + resource shrinking in release, and proguard-rules.pro already documents two pruning outages. Verify on the releaseTest build type, on device.

Record the extraction. A short section listing what moves to floret-kit (core-dav, core-sync, Login Flow v2, credential storage, the licence screen) and what stays app-local (the mapper, conflict policy and its UI, storage modes), so the follow-up branch is a file move and not a rediscovery.

Done when: the matrix is green where a server exists to run it against, the attribution screen ships, and a releaseTest build syncs on a real device.

What shipped, and what is still owed

Shipped in the chunk-5 commit — everything verifiable without a device or a live server:

• Attribution. Settings → Open source licenses, hand-maintained. Not a generated list: POM metadata routinely names a non-SPDX licence and points at a URL that 404s, so generators produce confidently empty output. dav4jvm is vendored, which makes MPL-2.0 §3.2(a) ours rather than a dependency's — the row names dav/PROVENANCE.md alongside upstream, because §3.2(a) is about where a recipient of the binary can obtain the source of what we modified.
• Revocation, both directions. A 401 escalates from the collection to the account, marks it, cancels its periodic work, and stops. Cancelling is the part that matters: Nextcloud throttles and then 429s per source IP, so a timer on a dead app password degrades every other Nextcloud client on that network. On removal, DELETE /ocs/v2.php/core/apppassword with OCS-APIRequest: true, best effort — without it, uninstalling never revokes anything and the password outlives the app in the user's device list.
• Play compliance. A privacy policy in docs/PRIVACY.md, linked in the app (the half that is usually missed) and declaring Collected, not Shared — "not collected" is indefensible when Play defines collection as transmission off-device regardless of recipient. A "delete this account's tasks from this device too" option on removal. REQUEST_IGNORE_BATTERY_OPTIMIZATIONS was already absent and stays absent.
• The server matrix, as far as a protocol mock can carry it: Nextcloud's no-uid-conflict, its trashbin 403 on a reused href, and share detection; SOGo's second-granularity opaque tokens and its triple resource type; Radicale advertising sync-collection without implementing it.

Still owed, and blocked on things a loop cannot do:

1. The live matrix. Four tests are @Ignored with their reasons written out rather than deleted: Baïkal on Digest, a CLASS:CONFIDENTIAL task on a shared Nextcloud calendar, an ETag-unchanged body change on SOGo, and Nextcloud's MKCALENDAR rate limit. Each names why a mock cannot stand in for it.
2. releaseTest on device, and the R8 outages proguard-rules.pro already documents.
3. The restore path, which needs a restore onto a fresh device — the one verification SYNC.md calls for explicitly and the one that cannot be faked.
4. cert4android, which replaces the current blanket user-CA trust and is a UI-bearing dependency.
5. Collection creation feature detection (OPTIONS → MKCALENDAR / extended MKCOL) and disabling the "new task list" affordance where neither exists. Deferred because the app has no CalDAV-side list-creation UI yet, so there is nothing to disable — it becomes real the moment that UI does.

Found by the review, and worth naming

⚠️ Revocation was aimed at the principal URL and revoked nothing. The OCS endpoint sits at the server root; the principal is …/remote.php/dav/principals/users/alice/, so appending to it produced a path that 404s on every server, every time — and the failure was swallowed as best-effort. The whole feature was a no-op. The root is now derived by cutting at remote.php, which is right for a subpath install too, with the origin as the fallback.

⚠️ Opening the app resurrected accounts a 401 had just stopped. ExistingPeriodicWorkPolicy.KEEP only keeps work that is unfinished, and CANCELLED counts as finished — so rescheduleAll() re-enqueued the very request the stop had removed, and put a dead app password back on a four-hour loop against a server that throttles by source IP. Exactly what the stop exists to prevent.

⚠️ The cursor advanced past bodies that were never applied. A network drop mid-multiget set report.failure and returned, and the incremental path stored the new token anyway — a permanent hole in the collection, invisible until the next full reconciliation a day later. runFull had this guard from the start; the incremental path did not.

Stopping an account cancelled the worker doing the stopping. syncTrigger.cancel kills both unique names, one of which is the WorkSpec currently executing — WorkManager interrupts the coroutine, so NeedsSignIn was never returned and the adapter saw CANCELLED rather than FAILED. The flag now does the work: sync() refuses before touching the network, and the schedule is cancelled from outside any worker.

"Sign in again" was a dead end. create is the only path that writes a credential and it rejected the duplicate name, so a user with a revoked app password could only remove the account — discarding the choice to keep its lists. It now re-authenticates in place, but only for an account already marked as needing sign-in, so a healthy credential can never be silently overwritten.

Four scalars were emitted twice. SEQUENCE, PRIORITY, PERCENT-COMPLETE and CLASS reach the residue verbatim when unparseable, and write authors them from their columns unconditionally — so a task read from SEQUENCE:x round-tripped carrying both SEQUENCE:0 and SEQUENCE:x. Invisible to the corpus, which filters SEQUENCE out of comparison entirely. Now suppressed, with a test that counts occurrences rather than comparing canonically.

A solidus-prefixed TZID was rejected as undefined — the rule's own comment says §3.2.19 exempts it. Thunderbird writes /mozilla.org/20050126_1/Europe/Berlin on every zoned task, so the validator would have quarantined every Lightning-authored task permanently.

Two smaller ones: a resource the query lists but the multiget will not return was re-requested for ever with nothing counting it, and account removal blocked on a 30-second connect timeout before anything visible happened.

What moves to floret-kit

Recorded here so the follow-up branch is a file move rather than a rediscovery. The rule that made it a move rather than a rewrite held: no task-domain type and no Android UI type crossed into the DAV or CalDAV layers.

Moves	Why it generalises
:dav (vendored dav4jvm) → core-dav	Not app-specific in any way; Calendula needs the identical tree
:caldav — discovery, CalendarCollection, sync-collection, quirks	Pure protocol, plain JVM, no Android types
NextcloudLoginFlow	Nothing about it is task-shaped
CredentialStore, CalDavAccounts, SyncAuthenticator	Keystore + AccountManager plumbing, identical for any CalDAV client
LicencesScreen / Attribution	Every app in the family owes the same notices

Stays app-local	Why
VTodoMapper, CalendarResource, ResourceValidator	VTODO ↔ our Room schema; the residue contract is ours
CollectionSyncer, SyncReport, conflict policy and its UI	Encodes decision 2, which is a product decision
SyncEngine, SyncWorker, SyncTrigger	Bound to our entities and our scheduling choices
Storage modes, External mode	Agendula-specific by construction

---

Definition of done, every chunk

1. It builds: ./gradlew :app:assembleDebug.
2. Unit tests pass: ./gradlew :app:testDebugUnitTest :dav:test :caldav:test. ⚠️ Name the plain JVM modules explicitly — testDebugUnitTest is an Android-variant task and does not exist on them, so their suites would otherwise be compiled by nobody and run by nobody. Add each new module here and to CI.
3. Lint passes: ./gradlew :app:lintDebug. Added after chunk 1 shipped a literal byte-order mark that builds and tests both accepted and CI's lint step would have rejected.
4. /code-review high on the chunk's diff, with the findings either fixed or answered in the commit message. For a chunk that vendors code, scope the review to the files we wrote — reviewing thousands of lines of verbatim upstream is noise, and its defects belong in PROVENANCE.md.
5. One commit per chunk, referencing the chunk number. No release, no tag.

Chunk 2 additionally does not count as done until the account-add UI has had an on-device review with an explicit go-ahead — CLAUDE.md's rule, and this is exactly the case it exists for.

What stops the loop

• A SYNC.md decision that the evidence overturns. Say so; do not pick the other branch silently.
• Anything requiring a real server that is not reachable — write the test, mark it skipped, name it in the commit, move on.
• Anything that would need a device beyond adb install.