Skip to content
SHC Docs

The frappe → Nextcloud calendar bridge

Status: open design. Phase 1 shipped, and phase 2 is built in part (2026-08-10). Phase 1 (§9.1) exists in full: apps/platform/frappe/nextcloud.plug.yaml, the calendar growth of apps/collaboration/nextcloud/nextcloud.socket.yaml, and the bench app at gitlab.com/bitspur/frappe/nextcloud (baked as a digest-pinned registry tarball). Phase 2 (§9.2) is built to exactly the line the owed rulings draw; see the status note in §9.2: the ledger, the User doc events, the hourly_long sweep and per-user generation revocation are in the bench app at commit 8b3ee4d (v0.2.0), and the provider-side job understands a revoked URL’s 410 + X-SHC-Feed-Generation answer. The effector rung is still RULING OWED (nothing consumer-side writes toward Nextcloud), and user_removed detection still waits on both an observer and ruling §11.1; the state exists in the schema and nothing sets it.

Replaces §2 of 2026-08-08-identity-and-edge-brokers.md, which held the stub open pending those probes.


Every claim in this document belongs to exactly one of three classes, and the class is stated at every use. Read this table before quoting anything.

ClassMeaningMarked
MEASUREDProbed against a live Nextcloud, 2026-08-08/09plain statement, dated
SPECIFIEDThis document decides it; no code exists”the app MUST…”
VERIFYA concrete assumption with the one command that settles itVERIFY
RULING OWEDAn owner decision, not an agent’s to makeRULING OWED

MEASURED, and the whole reason this document exists:

  1. The server-side write surface exists. occ dav:create-subscription <user> <name> <url> [color], occ dav:list-subscriptions <user>, occ dav:delete-subscription. There is no update command; changing a subscription’s URL is delete + recreate. There is no per-subscription refresh rate at create time.
  2. The cadence knob is app config: dav.calendarSubscriptionRefreshRate. Unset falls through to the code default P1D. A written PT5M sticks and takes effect; RefreshWebcalJob auto-registers per subscription and pulls the events. Proven end to end.
  3. Nextcloud refuses in-fabric feed hosts by default. Fetching a feed from a host on a private range needs allow_local_remote_servers=true, and frappe will be in-fabric.
  4. dav:create-subscription’s exact semantics, read off the pinned 34.0.2 image (apps/dav/lib/Command/CreateSubscription.php) by the socket-growth work in flight beside this document; see the note below:
    • it dedupes on the source URL, not the display name, and it fails (exit 1, “Subscription for url … already exists for this user”) rather than no-op. A converger must read that as success;
    • dav:delete-subscription <uid> <uri> takes the uri that dav:list-subscriptions <uid> prints in its first column, never the display name;
    • the color argument defaults to the theme’s primary when omitted.

★ A concurrent, uncommitted change is growing nextcloud.socket.yaml in this same worktree: an opt-in per-consumer admin grant (occ user:auth-tokens:add on the admin account, mint-and-returned), plus ocsUrl, adminUser and a read-back calendarRefreshRate. This document is written against that shape rather than around it. Two of its conclusions come straight from that work (the semantics above, and §7’s refusal to write the cadence knob from an edge), and where the two designs met independently on the same three phase-2 write paths (§9.2) that agreement is worth more than either statement alone.

The gap that closes: §2 of the 2026-08-08 doc said the Nextcloud side might need “a ~10-line admin-authed endpoint in a helper store app”. For phase 1 it does not. occ is enough, and occ is reachable from exactly one place, which is what fixes every placement decision in §4.


ERPNext holds the work calendar: the meeting booked off a Lead, the site visit on a Project, the interview on a Job Applicant. Nextcloud holds the personal calendar and is the thing already federated into every user’s phone and laptop. Today those are two windows, and the ERPNext one is only open while a browser tab is.

The bridge makes each user’s ERPNext events show up in their Nextcloud calendar list, without that user pasting a URL, without an admin creating anything per person, and without ERPNext events becoming editable in a place ERPNext cannot see.

One-way, read-only, ERPNext → Nextcloud. Nothing a user does in Nextcloud travels back. That is not a v1 shortcut deferred for later: a writable mirror makes Nextcloud a second author of a document ERPNext owns, and the merge question that follows has no good answer at this altitude.


2. Topology: a webcal subscription, not a CalDAV push

Section titled “2. Topology: a webcal subscription, not a CalDAV push”

Two designs reach “the user sees ERPNext events in Nextcloud”. The estate has one of each on the table, and they are not variations; they invert who does the work.

A. CalDAV push (bridges/huly-nextcloud)B. webcal subscription (this doc)
who writes eventsthe bridge, PUT per event, If-Match on a recorded ETagnobody; Nextcloud GETs one ICS document
who owns the collectiona service account; the human is a read-only shareethe human owns the subscription
per-event stateone row per event (uid, etag, last push)none
a deleted eventneeds a DELETE the bridge must not missdisappears from the next fetch
a 6-hour bridge outageevents silently stale until it returns; the ledger healsthe feed is computed at fetch time, so nothing was ever stale
credentials neededone service account, or per-user app passwordsnone in phase 1
freshnessseconds (push)the refresh rate (§7)
write surface requiredfull CalDAV against another principalone occ invocation, once per user, ever

B, and the deciding argument is the fourth row. A push bridge’s ledger exists because the representation lives on the far side and can drift from the source; a subscription has no far-side representation to drift. What is still needed per user is a subscription object, created once, then inert. That collapses the ledger from “one row per event, forever” to “one row per user, written twice”.

huly-nextcloud reached A for a reason that does not apply here: Huly’s source of truth is a transaction queue with no queryable “all events for user X at time T” view, so a push was the only shape available. Frappe has a database and a web worker; it can answer that query on demand.

What B gives up, honestly: freshness is polled, not pushed (§7); the subscription is an object the user owns and can delete (§6.4); and the feed URL is a bearer capability in a query string (§5.3).


3. What Nextcloud’s occ surface actually constrains

Section titled “3. What Nextcloud’s occ surface actually constrains”

Three constraints follow directly from the measured surface, and each one removes an option that would otherwise look reasonable.

3.1 No update command ⇒ a URL change is a delete + recreate

Section titled “3.1 No update command ⇒ a URL change is a delete + recreate”

The subscription’s source cannot be edited from occ. Any change to the feed’s origin, path, query shape or token forces the pair. Consequences:

  • The user-visible object is destroyed and rebuilt. Whatever the user did to that calendar in the Nextcloud UI, renamed it, recolored it, hid it from the month view, is client-side state keyed on the collection, and it does not survive. URL churn is user-visible damage, not a no-op.
  • The order must be create-then-delete, never delete-then-create. A failed create after a successful delete leaves the user with nothing and the job with no way to tell that state apart from “never subscribed”. Create the new subscription, read it back, then delete the one carrying the old source. A brief duplicate is the cost, and it is much the cheaper failure.
  • Therefore the URL is designed to be stable for the life of the deployment (§5.3): no version segment, no scheduled token rotation, and the origin stated once as an operator variable rather than derived from anything that moves.

Two measured details make the code that does this shorter than the paragraph above suggests. dav:create-subscription dedupes on the source URL and exits 1 when that URL is already subscribed for the user, so the converger needs no “does it exist” query on the happy path at all: it creates, and reads the failure as converged. And dav:delete-subscription takes the uri from dav:list-subscriptions’ first column, not the display name, so the display name stays purely human and is never part of any identifier.

3.2 No per-subscription refresh rate ⇒ the cadence knob is instance-wide

Section titled “3.2 No per-subscription refresh rate ⇒ the cadence knob is instance-wide”

dav.calendarSubscriptionRefreshRate is app config on dav. Writing it changes the refresh interval of every subscription on the instance, including ones users added themselves; a household holiday feed that refreshed daily now refreshes 96 times a day if the bridge sets PT15M. §7.2 is why the bridge does not set it at all.

3.3 occ is reachable from exactly one place

Section titled “3.3 occ is reachable from exactly one place”

occ is a PHP CLI inside the Nextcloud container. Nothing in the frappe stack can invoke it, and SHC offers no cross-stack request-time exec: the in-stack exec broker proposal (itself unbuilt) lists “cross-stack or cross-tenant targets” among its hard nos. So every subscription write happens in a provider-side job, and the only question left is who tells that job what to write.


4. The five mechanics that fix every placement decision

Section titled “4. The five mechanics that fix every placement decision”

These are properties of the engine, not preferences. Each one was learned the expensive way somewhere else in the catalogue.

4.1 A provider-side socket job is the only thing that can run occ. Follows from §3.3. jobs.integration on nextcloud.socket.yaml execs into the nextcloud service; a plug’s post_deployment job execs into a consumer service.

4.2 A consumer plug’s post_deployment job cannot read a minted value. runConsumerPlugPostDeploymentJobs builds its context from the statically rendered socket data; MergeJobMintedValues writes into the map the compose and hook render reads. apps/devops/sonarqube/gitlab.plug.yaml documents the whole mechanism, and it is why SonarQube’s GitLab work lives in app.yaml hooks. Consequence here: any consumer-side job that needs a Nextcloud credential must be a post_install/post_update hook job, not a plug job. In phase 1 no such credential exists, so this constraint costs nothing; it is recorded because phase 2 walks straight into it.

4.3 On a fresh install the consumer is not up when the socket’s integration jobs run; on an update it is. Phase order is discovery → integration (provider) → compose up (consumer) → post_deployment (consumer) → post_install hooks. On shc update the old containers still serve while phases 1–2 run (the same property that makes pre_update the only gate that can refuse safely, X409005HKGATE). So a provider-side job that dials the consumer works on every update and defers on a first install. §9.1 makes that deferral an explicit, loud, actionable state rather than a failure.

4.4 The provider reaches the consumer by short service alias. Attaching a consumer service to the provider’s network publishes that service’s short name as a DNS alias on it (docs/app-development/plugs-and-sockets.md, the services: pin). So from the Nextcloud container, a frappe stack that pinned services: [frappe-web] is reachable at http://frappe-web:8000. The hazard is in the same sentence: two frappe stacks bound to one Nextcloud both publish frappe-web, Docker round-robins, and half the subscriptions point at the wrong bench. §8.1 turns that into an identity check rather than a warning.

4.5 Crons see no integrations. A job run outside an install builds no integrations namespace (the same fact that makes SonarQube’s hook jobs no-op on a bare hook run). So a crons: entry on the Nextcloud stack cannot read the plug data it would need. VERIFY: read execute_job_task’s render context before relying on the negative; if it holds, a cron-driven backfill needs the edge’s parameters persisted somewhere the cron can read, which is a phase-2 design and not a phase-1 shortcut.


It does not exist. What follows is its specification.

5.1 Name, home, and why one app rather than two

Section titled “5.1 Name, home, and why one app rather than two”

frappe_nextcloud, module Nextcloud Bridge, repo gitlab.com/bitspur/frappe/nextcloud (the bitspur/frappe/* convention frappe_keycloak already follows).

One app per provider edge, not one per feature. The estate already has a second frappe↔Nextcloud need in flight: the file picker’s frappe shim (bridges/nextcloud-picker/frappe-shim/). Under the bake rule (§8.5) every new bench app is an image rebuild plus a pin bump plus a provenance assertion, forever. Two apps for one edge doubles that cost permanently, and the plug is one plug. The calendar bridge is the first module inside frappe_nextcloud; the picker shim is the second when it lands.

Precedents for the shape, both in bridges/: frappe_medusa (doc events → enqueue → converge, scheduler sweep, per-object map doctypes) and erpnext_keycloak (provenance markers, a write boundary enforced by a test). This app is smaller than either.

One endpoint. frappe.whitelist(allow_guest=True) on a GET:

GET <feedBase>/api/method/frappe_nextcloud.api.feed?u=<email>&t=<token>

The status codes are a contract, because §6.1 makes the provider-side job read them as the both-ends-exist test:

CodeMeaningWhat the socket job does
200 text/calendarboth ends exist; body is the user’s VCALENDARcreate or converge the subscription
404no enabled ERPNext user with that emailskip; delete an existing subscription for this edge
401the token does not verifyrefuse loudly; this is a misconfigured secret, never a missing user
429rate limiteddefer, change nothing
connection refused / DNS failurefrappe is not updefer, change nothing

The app MUST set frappe.local.response["http_status_code"] explicitly on every branch. VERIFY at implementation: frappe’s default is to answer 200 with an error payload for several failure shapes, which would make a missing user read as “subscribe them”.

The response MUST carry ETag (a hash of the rendered body) and honor If-None-Match with a 304. Nextcloud’s refresh is a plain GET per interval per subscription; a 304 makes the steady state nearly free.

@rate_limit-decorate the endpoint. VERIFY the import path in frappe v15.

5.3 The auth model: a tokenized URL, and why not a bearer

Section titled “5.3 The auth model: a tokenized URL, and why not a bearer”

Decision: a capability token in the URL, derived by HMAC. Not a bearer header, and not an API key.

The argument is mechanical before it is anything else: a Nextcloud subscription has exactly one field that can carry a secret: the source URL. dav:create-subscription takes user, name, URL and color. There is no header map, no credential reference, and no place to put an Authorization value. RefreshWebcalJob fetches the stored URL. A bearer token has nowhere to live, so the choice is between a token in the URL and no authentication at all.

Not the alternatives:

  • Not frappe’s api_key:api_secret. That credential is account-wide REST access for the user it belongs to. Putting it in a URL that lands in a database column any Nextcloud admin can read, and in the user’s own browser when the Calendar app shows the subscription’s source, would trade a calendar for an ERP session.
  • Not “unauthenticated, it’s only calendars”. A user’s meeting subjects are the shape of their work: customers, candidates, disputes. An unauthenticated per-user feed is an enumeration oracle over the whole staff.

The token shape:

t = base32( HMAC-SHA256( feedSecret, "<lowercased-email>|<generation>" ) )[:32]
  • feedSecret is one deployment-wide secret, ref+vault://calendar_feed_secret?autogen, never auto-rotated. Both ends compute from it: the bench app to verify, and the provider-side job to construct the URL without asking frappe anything. That second property is what makes phase 1 possible with no ledger and no enumeration endpoint.
  • generation is per user, default 1, read from the ledger when the ledger exists (§5.6) and assumed 1 when it does not. Bumping it is how a single user’s feed is revoked, and because the URL changes, revocation is correctly expressed as a delete + recreate (§3.1). This is why generation is in the HMAC input from day one and never in the query string: adding it later would change every URL in the estate at once.
  • Verification is a constant-time compare of the recomputed value.

What this leaks, stated plainly. The token appears in the frappe web server’s access log, in Nextcloud’s oc_calendarsubscriptions.source column, and in the subscription’s own detail view for the user who owns it. The first is the only one that matters, and the blast radius of the leak is one user’s calendar, read-only, revocable by a generation bump. That is an acceptable trade for a capability that cannot be expressed any other way; it would not be acceptable for a credential with any write scope, which is exactly why the token grants none.

The email in the URL is deliberate: it makes verification stateless on both ends. An opaque token that must be looked up requires an index, and an index requires the ledger to exist before the first subscription can be created, which is the dependency phase 1 exists to avoid.

doc_events, in hooks.py, in two families with two different purposes:

doc_events = {
"User": {
"after_insert": "frappe_nextcloud.calendar.tasks.on_user_changed",
"on_update": "frappe_nextcloud.calendar.tasks.on_user_changed",
"on_trash": "frappe_nextcloud.calendar.tasks.on_user_trashed",
},
"Event": {
"after_insert": "frappe_nextcloud.calendar.tasks.touch_feed",
"on_update": "frappe_nextcloud.calendar.tasks.touch_feed",
"on_trash": "frappe_nextcloud.calendar.tasks.touch_feed",
},
}

★ The Event hooks are a cache concern, not a correctness concern, and saying so is the point. In a push bridge, missing an event hook means the far side is permanently wrong. Here the feed is computed at fetch time, so a missed hook costs nothing but a stale ETag. touch_feed bumps a per-user feed version so the 304 path stays honest; a bug in it degrades to “the ETag always changes”, never to “an event is missing”. Nothing in this app enqueues a write to Nextcloud from an Event hook, and nothing should.

The User hooks are the ones that matter, and only in phase 2: a new or newly-enabled user is the moment a subscription becomes possible, and a disabled or deleted user is the moment it must go away.

scheduler_events (phase 2) run the level-triggered sweep; hourly_long is the right rung; the medusa precedent uses */5 for a poll that has a queue behind it, and this one does not.

VERIFY: the frappe stack runs bench schedule (confirmed in apps/platform/frappe/compose.yaml), but a site can still carry pause_scheduler/scheduler_enabled from a restore; frappe.exporter.yaml already names both as source-deployment posture that a restore must not carry in. A phase-2 preflight must assert the scheduler is live, because a paused scheduler makes the loop silently stop converging.

In phase 1: nothing. The provider-side job owns every write. The bench app is a read surface and a secret verifier.

In phase 2 it needs an effector, and that is the one genuinely open design question in this document, §9.2.

One doctype, Nextcloud Calendar Link, one row per ERPNext user. Named hash, permissions System Manager only, track_changes off.

fieldtypewhy
userLink → User, unique, reqdthe ERPNext end
match_emailDatalowercased; what the match was made on, frozen
nc_user_idDatathe Nextcloud uid, empty until observed
generationInt, default 1the revocation counter of §5.3
stateSelectpending / active / user_removed / revoked
subscription_sourceDatathe URL last written into Nextcloud; the delete+recreate trigger is != desired
last_seen_nc_atDatetimewhen the Nextcloud end was last observed to exist
last_converged_atDatetime
attempts, last_errorInt, Small Textthe medusa/keycloak shape

No token column. The token is derived (§5.3), so storing it would create a second copy that can drift and a secret to protect for no gain. This also sidesteps the __Auth trap the estate has already been bitten by: a frappe Password field lives Fernet-encrypted in __Auth, and an undecryptable one reads as absent: a feed that 401s for a user whose row looks perfect.

ICSfrappenotes
UID<Event.name>@<site>stable across edits; the site suffix keeps two benches from colliding in one client
SUMMARYsubject
DESCRIPTIONdescriptionHTML stripped to text; ICS has no HTML body
DTSTART / DTENDstarts_on / ends_onconverted to UTC, emitted with Z
all-dayall_dayVALUE=DATE, DTEND exclusive (the classic off-by-one)
RRULErepeat_this_event, repeat_on, repeat_till, weekday flagsDaily/Weekly/Monthly/Yearly → FREQ=; weekday flags → BYDAY
STATUSstatus / event_type == "Cancelled"CANCELLED rather than omission, so a client that cached it clears it
LOCATIONfirst non-empty of the location-ish fieldsVERIFY the field name on v15
SEQUENCEmonotonic from modified
LAST-MODIFIED, DTSTAMPmodified, now

Timezones: convert to UTC and emit Z. Frappe stores naive datetimes in the site’s System Settings.time_zone. Emitting a VTIMEZONE block is more faithful and much easier to get subtly wrong; UTC is unambiguous and every client renders it in the viewer’s zone. A site whose time_zone is unset must make the feed refuse (500 with a named cause) rather than silently assume UTC and shift every meeting.

VERIFY the exact v15 field names above against frappe/desk/doctype/event/. No frappe source tree was available while writing this; the field set is from working knowledge of the v15 Event doctype and must be confirmed before code.

Explicitly out of scope for v1, and named so nobody has to re-derive whether they were forgotten: HRMS Leave Application and Holiday List, Project/Task deadlines, Appointment, and any doctype-to-calendar mapping that is not the Event doctype. Each is a separate feed at most, never a widening of this one.

The feed for user X contains events where X is the owner, or X is named in event_participants. Public events (event_type == "Public") are included only when vars.nextcloud.includePublic is true, default false; an estate that books every company holiday as a Public Event would otherwise push it into every personal calendar without anyone deciding to.

The app MUST derive that set with an explicit query it owns, not by calling a desk helper under frappe.set_user(). A permission-derived answer inside a guest request is one refactor upstream away from either leaking or emptying, and the rule above is three lines of SQL that a test can pin.


Doctrine: converge only when both ends exist. The naive reading needs two lookups, “does the Nextcloud user exist” and “does the ERPNext user exist”, and the second one is what would force an enumeration endpoint, a credential, or both.

It collapses to one request. The provider-side job already enumerates Nextcloud users with occ (that end is free, it is running inside Nextcloud), computes the candidate feed URL from the email and the shared secret (§5.3), and then GETs the URL it is about to subscribe them to. A 200 proves the ERPNext end exists, proves the token verifies, proves the network path works, and proves the document parses, before any subscription is created. A 404 proves the far end has no such user.

The property that buys: this design cannot create a dead subscription. The recurring failure this catalogue keeps finding, a write that succeeds against coordinates that were never reachable, is structurally unavailable here, because the reachability check is the precondition.

(no NC user with this email)
┌── absent ────────────────────────────────────────┐
│ │
│ NC user appears feed GET 200 │
└──▶ pending ──────────────────────────▶ active ───┤
▲ │ │
│ NC user deleted │ │ ERPNext user
│ (subscription died with them) │ │ disabled/deleted
│ ▼ ▼
└─────────────────────────── user_removed / revoked
  • pending: a Nextcloud user exists, the ERPNext side does not (404) or frappe was unreachable. Nothing is written. Re-evaluated every pass.
  • active: the subscription exists and its source equals the desired URL.
  • user_removed: the subscription was there last pass and is gone now (§6.4).
  • revoked: the ERPNext user is gone or disabled; the subscription was deleted by the bridge.

An ERPNext user with no Nextcloud account. Nothing happens, and nothing is recorded on the Nextcloud side, because the loop enumerates from Nextcloud. The user simply has a feed nobody fetches. That is the correct behavior: the bridge does not create Nextcloud accounts. (Account creation is the identity-broker’s job, and it is a different document.)

A Nextcloud user who appears later. Picked up by the next pass: the next shc update in phase 1, the next hourly sweep in phase 2. No event, no callback, no ordering requirement between the two stacks’ installs. This is the level-triggered property earning its keep: there is no “the user was created during the window” bug because there is no window.

what was deletedwhat happenswho does it
an Eventit is absent from the next feed rendernobody; this is the subscription model’s whole payoff
an ERPNext user (or disabled)the feed 404s; the bridge deletes the subscription and marks revokedprovider-side job
a Nextcloud userthe subscription dies with the account (Nextcloud cascades); the row returns to pending so a re-created account re-convergesNextcloud, then the loop
the subscription, by the user, in the Nextcloud UIRULING OWED; see belowundecided
the edge (-i nextcloud! or uninstall)every subscription whose source starts with this edge’s feed base is sweptsocket unintegration job
the feed secret (deliberate rotation)every URL changes ⇒ create-then-delete for every user, one passprovider-side job, loudly

★ RULING OWED: what happens when the user deletes the subscription themselves. The two answers are both defensible and they are opposite:

  • Respect it (recommended). Detect “present last pass, absent now”, record user_removed, and stop re-creating. A bridge that re-creates a calendar the user deleted is a bridge the user cannot escape, and the subscription is an object the user owns, unlike huly-nextcloud’s Pattern A, where the user can only unshare a view of a collection the service account owns, which is why that bridge re-converges without qualm.
  • Re-create it, because the flagship bar is zero-touch and an admin-decided calendar is not the user’s to decline.

The recommendation is respect, with the removal reported rather than silently absorbed, and no --var to override it (a knob here just moves the ruling to whoever types the install command). This is stated as a ruling owed rather than decided because it is the one edge in this design where the software’s answer decides whether a user has a way out.

Detecting it needs the ledger, which is why it is a phase-2 behavior. In phase 1 a deleted subscription is re-created on the next update, and §9.1 says so in the operator-facing text rather than pretending otherwise.

6.5 Surviving the delete + recreate constraint

Section titled “6.5 Surviving the delete + recreate constraint”

Rules that follow from §3.1, all of which the implementation must hold:

  1. Create the new, read it back, then delete the old. Never the reverse.
  2. Match the old by source prefix, and delete by uri. The display name is human-facing (“ERPNext”), stays stable and unprefixed, and is part of no identifier anywhere; measured: create dedupes on the source URL, and delete takes the uri from dav:list-subscriptions’ first column. The URL origin is the edge’s identity handle, exactly as the GitLab socket uses a token-name prefix.
  3. Nothing in the URL may derive from anything that moves. Not the stack name, not a container alias that a second consumer could shadow (§4.4), not an app version, not a date. vars.nextcloud.feedBaseUrl is stated once by the operator or defaulted to the pinned short alias, and changing it is understood to rebuild every subscription in the estate.
  4. The secret is never rotated on a schedule. ?autogen mints once. A deliberate rotation is a fleet-wide rebuild and must announce itself in the job log as one.

7. The refresh rate: what to set, and who is allowed to set it

Section titled “7. The refresh rate: what to set, and who is allowed to set it”

The value is PT15M. The writer is the OPERATOR, not this integration.

Those are two decisions and the second one reverses an earlier draft of this section, so the reasoning for each is separate.

The reasoning, in the two directions that matter:

  • Down from the P1D code default, because a day-old work calendar is not a calendar. The unset default is what makes this knob mandatory rather than optional.
  • Not PT5M, even though PT5M is what the probe proved. The cost is not the HTTP request (one conditional GET per user per interval against frappe’s own web workers, answered with a 304 in the steady state, negligible at any plausible headcount). The cost is that this knob is instance-wide (§3.2): every subscription any user ever added gets the same interval. PT15M is fast enough that an event booked in a meeting shows up before the meeting ends, and slow enough to be defensible as a new floor for feeds the bridge does not own.

7.2 The writer, and why not the integration

Section titled “7.2 The writer, and why not the integration”

An earlier draft had the socket write the knob under a composition rule (write if unset, write if the stored value is longer, never lengthen someone else’s tighter value). That is the wrong posture, and the socket-growth work in flight (§0) states the reason better than the rule answers it: the knob is instance-global, so an edge-clocked write lets the last consumer to bind retune every other consumer’s feeds. The never-lengthen rule stops the worst case, and it still leaves a subscription somebody else created being fetched four times an hour because an ERP was installed. Provider-global configuration is not a consumer’s to converge, the same boundary docs/proposals/2026-08-07-config-vs-state-migration.md draws elsewhere.

So the posture is detection, never reconciliation, which is exactly what the frappe package already does for the three facts it can observe and must not repair (auth-secret-audit, login-path-audit, version-drift: all detection only, all loud, all changing nothing):

  • the socket publishes the effective value it read back (calendarRefreshRate, empty meaning “unset, so P1D”);

  • the bridge’s job compares it against vars.nextcloud.refreshRate (default PT15M, the value it wants);

  • if the instance is slower, the job says so, with the command, and subscribes anyway:

    nextcloud calendar: this instance refreshes webcal subscriptions every P1D
    (dav.calendarSubscriptionRefreshRate is unset, so the code default applies).
    ERPNext events will take up to a day to appear. Set it once, as operator:
    occ config:app:set dav calendarSubscriptionRefreshRate --value=PT15M
    It is INSTANCE-WIDE; it also retunes every subscription your users added
    themselves. This integration will not write it for you.

Never blocking on it is deliberate: a calendar that is a day behind is worth more than an install that refused, and the operator now has the one line that fixes it.

★ The knob is necessary and not sufficient, and this is the largest unverified dependency in the document. RefreshWebcalJob is a background job. Nextcloud only runs background jobs when a runner runs them, and apps/collaboration/nextcloud/ sets no backgroundjobs_mode, ships no cron container, and runs no cron.php; grep confirms it: the package has no such line anywhere. The official image does not run cron on its own. If the instance is in AJAX mode, background jobs execute one-per-page-load, so an idle Nextcloud refreshes nothing and the refresh rate is a floor that is never reached.

The probe proved the mechanism end to end, which does not establish that it fires unattended on an SHC-packaged Nextcloud. Settle it with one command:

Terminal window
occ config:system:get backgroundjobs_mode # expect: cron
occ background-job:list --limit 5 # expect RefreshWebcalJob rows advancing

and if the answer is ajax, the fix is a small, separately shippable piece of work on the Nextcloud package: a crons: entry running php -f /var/www/html/cron.php as www-data every 5 minutes, plus occ background:cron. Note the caveat apps/communication/matrix/app.yaml records for the first cron user in the catalogue: crons: only fires under a daemon, and on a CLI-thin install the row is never written and nothing warns.

This is a prerequisite of the bridge, not a part of it, and it benefits every other background job on the instance (notifications, previews, trash expiry, federated shares).

And note what the socket’s calendarRefreshRate read-back does not settle: it reports the configured interval, which says nothing about whether any runner is executing the jobs that honor it. A PT15M on an instance in AJAX mode is a number, not a cadence.


8.1 apps/platform/frappe/nextcloud.plug.yaml: new

Section titled “8.1 apps/platform/frappe/nextcloud.plug.yaml: new”

Frappe consumes the nextcloud socket. Not caldav, not calendar: the socket already exists, it is a singleton named for the app (its own header states why), and this is an additive consumer of it.

required: false # a calendar must never block an ERP install
services:
- frappe-web # Nextcloud dials IN to this service; the attach is
# what publishes the alias §4.4 depends on
# (the sweep handle is the feed URL, not a label)
data:
# ★ NO `label`. On this socket the label is the OPT-IN to the admin grant:
# declaring one mints a Nextcloud app password on the admin account, which
# carries the admin's full authority (no scopes exist). Phase 1 writes
# everything through occ inside the provider and holds NO Nextcloud
# credential, so asking for one would be taking the estate's most
# privileged secret to not use it. Phase 2 rung A adds the label on the day
# something consumer-side actually reads /cloud/users; see §9.2.
siteName: "{{ vars.siteName }}" # the identity check of §4.4
feedBaseUrl: "{{ vars.nextcloud.feedBaseUrl | default('http://frappe-web:8000') }}"
feedSecret: "{{ vars.nextcloud.feedSecret }}" # @secret
calendarName: "{{ vars.nextcloud.calendarName | default('ERPNext') }}"
calendarColor: "{{ vars.nextcloud.calendarColor | default('') }}"
refreshRate: "{{ vars.nextcloud.refreshRate | default('PT15M') }}"
includePublic: "{{ vars.nextcloud.includePublic | default(false) }}"
matchDomains: "{{ vars.nextcloud.matchDomains | default('') }}"

⚠ {{ stack }} in a plug data: render is the PROVIDER’s stack, not this one (sonarqube/gitlab.plug.yaml documents the trap; ce builds plugCtx with "stack": sp.ProviderStackName). That is why feedBaseUrl defaults to a literal short alias instead of a derived tenant FQDN, and, when phase 2 adds a label, why it must be built from tenant (which is the consumer’s) and never from stack, which would silently name the Nextcloud.

The identity check siteName exists for: the provider-side job GETs the feed and compares a X-SHC-Bridge-Site response header against integration.plug.data.siteName. A mismatch means the short alias resolved to a different bench (§4.4) and the job refuses the whole edge rather than subscribing users to a stranger’s calendar. This costs one header and removes an entire class of silent cross-tenant leak.

Also on this file: jobs.post_deployment with the consumer-side activation job (§8.3), and jobs.unintegration that sets the bridge’s mode to off on disconnect. Not bench uninstall-app; removing an app from a live site is the destructive half of the 2026-08-05 outage class, and a disabled bridge serving 404s is the correct terminal state.

8.2 apps/platform/frappe/vars.yaml: additions

Section titled “8.2 apps/platform/frappe/vars.yaml: additions”
nextcloud:
feedBaseUrl: "" # empty → the short alias; set to a public
# https origin when more than one bench binds
# one Nextcloud, or when the estate would
# rather not enable allow_local_remote_servers
feedSecret: "ref+vault://calendar_feed_secret?autogen"
calendarName: "ERPNext"
calendarColor: ""
refreshRate: "PT15M"
includePublic: false
matchDomains: "" # comma-separated; empty = every domain

with the matching vars: type declarations in app.yaml (feedSecret@secret, the rest @string/@boolean), each carrying the constraint that governs it; feedBaseUrl in particular must say that changing it rebuilds every subscription (§3.1).

8.3 The consumer-side job: activation and settings

Section titled “8.3 The consumer-side job: activation and settings”

frappe-configure-nextcloud-calendar, a post_deployment job on the plug, context: service, service: frappe-web. It mirrors frappe-configure-keycloak-connector line for line, because that job already solved this exact problem for frappe_keycloak:

  1. Refuse if the app is not on the bench, naming the image requirement, in the IMAGE-OWNED language the bats guard pins, never suggesting a vdeployment, never running bench get-app:

    Terminal window
    if ! ./env/bin/python -c "import frappe_nextcloud" 2>/dev/null; then
    echo "the nextcloud calendar bridge was requested but frappe_nextcloud is not on this bench." >&2
    echo "Plug mechanisms are IMAGE-OWNED (owner ruling 2026-08-08): baked in, activated" >&2
    echo "through vars, never installed as vdeployments. Point images.frappe at an image" >&2
    echo "that bakes frappe_nextcloud." >&2
    exit 1
    fi
  2. bench --site <s> install-app frappe_nextcloud when absent. Safe, per the corrected rule in the Dockerfile header: the code is already importable, so registration has no import window.

  3. bench --site <s> set-config the settings the app reads: shc_nc_calendar_mode, shc_nc_calendar_feed_secret, shc_nc_calendar_include_public, shc_nc_calendar_site. Site config, not environment, for the reason frappe_medusa/sync/settings.py gives: the web worker, the scheduler and a bench execute must all see one configuration, and only site config reaches all three.

  4. Read back and fail loudly: bench --site <s> execute frappe_nextcloud.api.preflight, asserting the app answers, the secret it holds matches (compared as a digest, never echoed), and the endpoint is registered. House discipline: no write in this catalogue is trusted by its exit code.

Why activation lives here and not in vars.activateApps. activateApps is the right home for an app every site should carry regardless of edges. This one is meaningful only when a nextcloud edge exists; activating it estate-wide would put a feed endpoint on benches that nothing subscribes to. Edge-scoped activation, edge-scoped teardown.

8.4 apps/collaboration/nextcloud/nextcloud.socket.yaml: additive growth

Section titled “8.4 apps/collaboration/nextcloud/nextcloud.socket.yaml: additive growth”

The socket reserved this from the start (“the admin capability grows HERE… additive keys, never a second socket”), and the in-flight growth of §0 has already taken the first half: the discovery keys, the label-gated admin grant, and grant-nextcloud-admin in jobs.integration.

Phase 1 needs none of that. No new data: key, no credential, no label (§8.1); every write is occ, inside the provider. What it adds:

schema.plug: the keys §8.1 sends (siteName, feedBaseUrl, feedSecret@secret, calendarName, calendarColor, refreshRate, includePublic, matchDomains), each described with its constraint, beside the label the grant already declares.

A SECOND job in jobs.integration: nextcloud-subscribe-calendar-feeds, after grant-nextcloud-admin, context: service, service: nextcloud, user: www-data (occ refuses to run as root; www-data owns config.php on this image). No timeout: field; the socket integration job struct has none, so writing one parses and then vanishes; the waits carry their own budgets. In order:

  1. No feedBaseUrl or no feedSecret → exit 0, “nothing to converge”.
  2. Probe the consumer once: GET <feedBase> health. Unreachable → exit 0, deferred, printing the exact remedy (§9.1). Never fail the bind: a Nextcloud that refused to finish binding because an ERP was mid-boot would be a worse product than a calendar that arrives one update later.
  3. If the feed host is in a private range: occ config:system:set allow_local_remote_servers --value=true --type=boolean, and say what it widens; the flag is instance-wide and lets every Nextcloud feature that fetches a URL (federation, external storage, webcal) reach private addresses. Skip it entirely when feedBaseUrl is a public origin, and say that too, so an operator can see which posture they are in.
  4. occ user:list → for each uid, occ user:info <uid> --output=json → email. Skip users with no email; refuse (loudly, without writing) when two users share one email; apply matchDomains when set. VERIFY whether user:list --info emits emails in one call; the per-user loop is N execs and is the slow part of this job on a large instance.
  5. Per candidate: compute the URL (§5.3), GET it, and branch on §5.2’s status table. On 200, compare X-SHC-Bridge-Site to siteName (§8.1) and refuse the edge on mismatch.
  6. Converge, using the measured semantics of §0.4: occ dav:create-subscription <uid> <name> <url> [color], and read “already exists for this user” (exit 1) as converged, not as a failure. Then occ dav:list-subscriptions <uid> for any subscription under this edge’s feed-base prefix carrying a different source, and occ dav:delete-subscription <uid> <uri> it; create first, delete second (§6.5), and the uri is the first column of the list, never the name.
  7. Compare the socket’s read-back calendarRefreshRate against vars.nextcloud.refreshRate and report (§7.2). This job never writes that knob.
  8. Print a one-line summary: created / converged / deferred / skipped counts. A convergence loop that cannot be read from its log is a convergence loop nobody trusts.

jobs.unintegration: nextcloud-sweep-calendar-feeds: for every user, delete every subscription whose source starts with the frozen feedBaseUrl from the edge state. Not lifetime: managed: this deletes a pointer the integration itself created, not user-authored data, the same reasoning that keeps GitLab’s token sweep ungated.

Because the owner ruled it, and because the ruling has a body count.

Plug mechanisms are IMAGE-OWNED: baked and vars-activated, never vdeployments (owner ruling 2026-08-08).

Pinned three ways already, all of which this app inherits:

  • apps/platform/frappe/tests/tests.bats: “no frappe plug declares a vapp dependency; mechanisms are image-owned” fails if any *.plug.yaml in the package grows a vapp: key. nextcloud.plug.yaml is inside that glob on the day it is created; no new guard is needed for the negative.
  • The same file asserts the OIDC plug’s refusal text says IMAGE-OWNED and never names shc install frappe/plugin.
  • frappe/docker/Dockerfile’s header records the 2026-08-05 outage: an app installed into a live preloaded gunicorn entered the site’s app list before the master’s cached sys.path could see it, and hq.flyingfoxlabs.in 500’d on every route until it was manually removed. The window is inherent to installing a Python app into a running preloaded gunicorn.

And a fourth reason specific to this bridge: the plug’s job refuses when the app is absent (§8.3). A vdeployment-delivered mechanism would make that refusal a race: bind before the vApp lands and the edge fails; bind after and it succeeds, which is precisely the class of ordering bug the bake rule deletes.

bridges/erpnext-keycloak/README.md still says it installs “through shc/apps/frappe’s plugin VApp like any other bench app”. That README predates the ruling. It is not a counter-example; it is a document owed an update.

frappe/docker/Dockerfile gains a second app, in the shape the first one established, and that shape is not decoration:

ARG FRAPPE_NEXTCLOUD_REPO=https://gitlab.com/bitspur/frappe/nextcloud.git
ARG FRAPPE_NEXTCLOUD_REF=<commit sha, never a branch>
RUN set -eux; \
git init --quiet apps/frappe_nextcloud; \
cd apps/frappe_nextcloud; \
git remote add origin "${FRAPPE_NEXTCLOUD_REPO}"; \
git fetch --quiet --depth 1 origin "${FRAPPE_NEXTCLOUD_REF}"; \
git checkout --quiet FETCH_HEAD; \
test "$(git rev-parse HEAD)" = "${FRAPPE_NEXTCLOUD_REF}"; \
cd /home/frappe/frappe-bench; \
./env/bin/pip install --no-cache-dir -e apps/frappe_nextcloud

Everything the existing file says applies unchanged and must be honored:

  • USER frappe, ./env/bin/pip and never bare pip; the outage’s second cause was an install that landed in system python while gunicorn ran from the bench venv.
  • A separate RUN asserting import frappe_nextcloud against ./env/bin/python, in a fresh layer over the committed filesystem.
  • Nothing under sites/ or logs/. tests/unit/ci/frappe_image_volume_writes_test.go enforces it, because Docker does not: under BuildKit a write to a VOLUME path persists into the published image and into a fresh named volume.
  • A commit sha, never a branch; two builds a week apart must not differ.
  • The provenance manifest assertion picks the app up automatically (record-versions.sh walks the bench), and frappe_nextcloud must be added to the manifest’s required-app list beside frappe, erpnext and frappe_keycloak.
  • images.frappe in vars.yaml and this FROM/app set are two halves of one decision; tests/unit/catalog/image_provenance_test.go reds if they drift.

★ And the trap that must be stated with the delivery, every time: the bench volume is seeded once. On an existing bakeApps: false deployment, the default, and what both live production benches run, .seeded already exists, so the new app does not arrive and there is no error. version-drift reports stale and names it, which is the only reason the no-op is visible. Delivering the bridge to an existing vapp-mode bench needs a deliberate, consented step (a reinstall with bakeApps: true, or the image-identity-keyed re-seed that is still open). Bumping the pin is not that step and must not be reported as one.

testasserts
apps/platform/frappe/tests/tests.batsthe new plug carries no vapp: (covered by the existing glob), the activation job says IMAGE-OWNED and never bench get-app, required: false, and services: pins frappe-web
samethe plug’s data: uses tenant and never stack (the provider-stack trap)
apps/collaboration/nextcloud/tests/tests.batsthe integration job never fails on an unreachable consumer (an exit 0 deferral branch exists), the refresh-rate write is conditional, and the sweep keys on feedBaseUrl and not on the display name
tests/unit/catalog/image_provenance_test.gothe Dockerfile app set and imageVersions agree (existing test, new row)
the app’s own repothe write boundary: no code path writes anything into Nextcloud, and no code path emits an event body from a doc hook

9.1 Phase 1: deploy-time backfill. Buildable today.

Section titled “9.1 Phase 1: deploy-time backfill. Buildable today.”

What ships: existing users get their ERPNext calendar in Nextcloud, and it stays correct forever. What is missing is only when new users are picked up.

Deliverables, in dependency order:

#DeliverableWhereNew component?
1frappe_nextcloud with one endpoint (§5.2), the HMAC verifier (§5.3), the Event→VEVENT mapping (§5.7), the visibility rule (§5.8), and preflighta new repothe bench app; see below
2The Dockerfile app + pin bumpfrappe/docker/Dockerfile, apps/platform/frappe/vars.yamlno
3nextcloud.plug.yaml + vars + the activation jobapps/platform/frappe/no
4schema.plug + jobs.integration + jobs.unintegrationapps/collaboration/nextcloud/nextcloud.socket.yamlno
5The guardsboth tests.batsno
6The background-job prerequisite (§7)apps/collaboration/nextcloud/a crons: entry, if the mode check says ajax

★ “No new component” is true of the SHC side and only the SHC side. There is no broker, no sidecar, no vApp, no daemon, no new socket and no new credential; items 2–6 are edits to files that already exist, using idioms that already exist in the same files. The bench app is genuinely new code, and there is no version of this feature without it: nothing in frappe core serves ICS. What phase 1 buys is that the app is one read-only endpoint plus a hash comparison: no ledger, no scheduler, no queue, no state, no Nextcloud credential, and no doctype. That is the smallest bench app in the estate, and it is exactly the part that phase 2 keeps unchanged.

How it converges, and the one rough edge. The backfill runs in the socket’s integration phase, which fires on every consumer install and every update (§4.3). On a fresh install frappe is not up yet, so the job defers, and must say so in words an operator can act on:

nextcloud calendar: frappe is not reachable at http://frappe-web:8000 yet.
On a first install this is expected; the consumer's containers start after
this phase. No subscription was created and nothing was changed.
Converge with: shc update <frappe-stack> -i nextcloud=<nc-stack>

Every later shc update of the frappe stack re-runs it and converges. So the operator’s clock is the update, which is honest for a deploy-clocked mechanism and is exactly what phase 2 replaces.

Acceptance for phase 1 (each line is a command, not a feeling):

  1. occ dav:list-subscriptions <uid> shows one subscription per matched user, with the expected source.
  2. curl -sS -o /dev/null -w '%{http_code}' "<feed url>" → 200; the same URL with a mangled token → 401; with an unknown user → 404.
  3. A second shc update creates nothing and reports “converged” for every user, the idempotency assertion, and the one most worth automating.
  4. With the knob unset, the job’s log carries the P1D warning and its remedy line (§7.2) and still subscribes; after the operator runs the command, occ config:app:get dav calendarSubscriptionRefreshRate → PT15M and the next run’s log is quiet.
  5. An event created in ERPNext appears in the Nextcloud calendar within one refresh interval, which is where §7’s background-job check gets settled for real.
  6. shc update <frappe-stack> -i nextcloud! leaves zero subscriptions carrying the feed base.

What it adds: the ledger (§5.6), the User doc events and the hourly sweep (§5.4), the user_removed detection (§6.4), and per-user revocation via generation (§5.3). New users are picked up in minutes with no operator action.

STATUS 2026-08-10: built to the line the owed rulings draw. Landed in frappe_nextcloud 0.2.0 (commit 8b3ee4d): the ledger doctype (rows are UNLINKED on user deletion, never deleted; a deleted row would reset the generation and re-arm every revoked URL; on_trash runs before frappe’s link check, which is what lets the User be deleted at all), the User doc events and hourly_long sweep funnelling into one level-triggered reconcile, per-user revocation (bench nextcloud-revoke-feed --user <a>), and a preflight that asserts the ledger table and the scheduler pulse (§5.4’s VERIFY). The wire growth this forced, which §5.3 left implicit: the provider-side job derives every candidate at generation 1 with no ledger to consult, so a bumped user’s feed answers that probe 410 with X-SHC-Feed-Generation: <current>, distinct from 401 (which stays the refuse-the-edge secret-mismatch verdict) and disclosed only to a caller presenting a token that once verified; the socket job re-derives at the announced generation and the revocation lands as the delete + recreate of §3.1, scoped to one user. Generation 1 stays classifiable as stale at any distance (bounded window otherwise) or the job would read its own bootstrap as a mismatch. NOT built, still owed: the effector rung below (so new-user pickup remains update-clocked, not minutes), the observation surface, and user_removed detection; the recommended respect reading is honored passively (nothing flips a user_removed row back to pending), but nothing SETS the state, because detection needs an observer and the ruling is not this code’s to make.

The open question is the effector, and it is genuinely open: the bench app runs consumer-side and occ is provider-side (§3.3). Three rungs, ranked, with what each costs:

RungHow the loop writesCostDoctrine fit
A. One-capability helper on the Nextcloud sidea route wrapping createSubscription, admin-authed with a per-consumer app password the socket mints (gitlab shape)the credential half is already built (§0): declare a label and the grant arrives. What remains is a bespoke Nextcloud app with no store release, so it must itself be image-owned: an SHC-built Nextcloud image, which the estate does not have. And the grant is admin-equivalent; Nextcloud exposes no scoped admin token, and occ no --scope.clean: consumer-side loop, provider publishes one generic capability, never pair logic
B. Login-time convergenceat the user’s next SSO login, frappe exchanges their token for a Nextcloud-audience one and the user’s own client creates the subscription over CalDAV MKCOLneeds the Keycloak audience mapper and bearer-CalDAV probes, still open, and shared with the picker. A user who never logs into ERPNext never gets a calendar, and deletions wait for a login.clean, and it needs zero stored credentials, the strongest property on the table
C. Provider-side cron pulling the consumer’s desired seta crons: job on the Nextcloud stack calling a frappe enumeration endpointcheapest to build, but blocked on §4.5 (a cron sees no integrations), so the edge’s parameters must be persisted somewhere the cron can readviolates placement: an edge-broker living provider-side is what doctrine reserves for the identity-broker alone

Recommendation: B if its probes go green, A otherwise, never C. B is the only rung that needs no credential at all, and its weakness (a user who never logs in) is bounded by the fact that phase 1 already covers everyone at every update. RULING OWED on the rung, and it is not urgent: phase 1 ships without choosing.

★ Worth recording that the socket-growth work (§0) enumerated the same three paths, in the same order, independently, per-user bearer via token exchange, a provider-side occ job for backfill, a helper endpoint in a Nextcloud app, and reached the same conclusion, that until one is proven the socket grants observation only. Two designs converging on one taxonomy is the strongest evidence available that the taxonomy is the real one.

Observation, in phase 2, comes from the grant rather than from occ: the consumer-side loop reads <ocsUrl>/cloud/users/details with the minted app password (OCS-APIRequest: true on every call) instead of enumerating from inside the provider. That is what makes the loop consumer-side at all, and it is the moment the frappe plug declares its label (§8.1).

Note the ordering trap phase 2 inherits from §4.2: any consumer-side job that reads a minted Nextcloud credential must be a post_install/post_update hook job, not a plug post_deployment job. Rung A walks into this on day one.

Nextcloud → ERPNext writes of any kind. Contacts (the org address book is huly-nextcloud’s Pattern A and a different mirror). Free/busy and scheduling. Per-user calendar creation in Nextcloud. HRMS leave, holidays, project deadlines (§5.7). Multi-site benches serving one feed per site to one Nextcloud user; one bench, one feed, per user.


10. Remaining unknowns, each with the command that settles it

Section titled “10. Remaining unknowns, each with the command that settles it”

Ranked by what they would cost if the assumption is wrong.

#UnknownSettles withIf wrong
1Does the Nextcloud instance run background jobs unattended? (§7)occ config:system:get backgroundjobs_modethe whole feature appears to work and refreshes approximately never; fix is a crons: entry on the Nextcloud package
2Do frappe guest-whitelisted methods let a handler set an arbitrary HTTP status? (§5.2)one endpoint, curl -w '%{http_code}'the both-ends-exist test of §6.1 collapses; a missing user would read as 200 and everyone gets subscribed
3The frappe v15 Event field names and recurrence flags (§5.7)read apps/frappe/frappe/desk/doctype/event/event.json on the pinned imagethe mapping is wrong in detail, not in shape; no source tree was available while writing this
4Does a crons:-run job see an integrations namespace? (§4.5)read execute_job_task’s render context in cechanges only which rungs are available in phase 2
5Does occ user:list --info emit emails in one call? (§8.4)occ user:list --info --output=jsonthe backfill is N execs on a large instance, slow, not wrong
6Does Nextcloud honor userinfo credentials in a subscription source URL?subscribe to https://u:p@host/... and watch the fetchirrelevant if it does; the token design does not need it and should not adopt it

Settled while this was being written, by the socket-growth work of §0, and recorded here because an earlier draft carried both as open: the source URL is what dav:create-subscription dedupes on (and it exits 1 rather than no-op), and dav:delete-subscription <uid> <uri> takes the uri from dav:list-subscriptions’ first column. The display name is part of no identifier.

★ And the largest one, stated without hedging: the bench app does not exist. Not a stub, not a branch, not a scaffold. Every “the app MUST…” above is a specification written before the code, and the first implementation pass will find things this document got wrong. The two probes settle the platform questions, which is what unblocked the design, and settle nothing about the app.


  1. The user deletes their subscription (§6.4): respect it (recommended) or re-create it. This decides whether a user has a way out of a bridge an admin turned on.
  2. The phase-2 effector rung (§9.2): A, B, or a refusal to build phase 2 at all until a second consumer needs the same capability. Not urgent; phase 1 ships without it.
  3. allow_local_remote_servers as a default (§8.4): the job can enable it silently when the feed is in-fabric, or refuse and require an explicit --var acknowledging that it widens what every Nextcloud fetcher can reach. The recommendation is enable and say so loudly, because the alternative posture, give frappe a public origin, is the better answer and should be the documented one.

Not owed, because it is decided: who writes dav.calendarSubscriptionRefreshRate. The operator does; the integration detects and reports (§7.2). An earlier draft of this document had the socket write it under a composition rule, and that draft was wrong.