Merge pull request #4145 from vitorpamplona/claude/elegant-shannon-ej3z9c

NIP-52: Add relay hints for calendar RSVPs and appointments

.claude/CLAUDE.md

@@ -224,9 +224,21 @@ version. `quartz/` is protocol-only — no composables.
 # Build Quartz for all targets
 ./gradlew :quartz:build
 
-# Run tests
+# Run the JVM tests of every module, KMP ones included. KMP modules register no
+# `test` task of their own; the root build aliases it onto their jvmTest.
 ./gradlew test
 
+# A single module. For a KMP module name jvmTest directly:
+./gradlew :quartz:jvmTest --tests "com.vitorpamplona.quartz.nip52Calendar.*"
+
+# NOT covered by `test`: each KMP module's OTHER targets, notably
+# :quartz:testAndroidHostTest (~3.9k tests, its own androidHostTest source set).
+# Nothing runs it today - not `test`, not pre-push, not CI - and it has 4 known
+# failures on main (NostrServerTest x3, LiveNegentropyIndexStoreTest x1), which
+# is why the alias maps to jvmTest rather than allTests. Run it explicitly when
+# touching relay-server or store code:
+./gradlew :quartz:testAndroidHostTest
+
 # Format code
 ./gradlew spotlessApply
 ```

.git-hooks/pre-push

@@ -16,11 +16,21 @@ echo "Running test... "
 # variants of :amethyst (play/fdroid × debug/release/benchmark) plus full
 # native-libs merging per variant — ~6× the work of one variant. CI runs the
 # multi-flavor matrix on push to main; pre-push only needs one happy path.
+#
+# Every KMP module's tests live under <module>:jvmTest - the Kotlin Multiplatform
+# plugin registers no plain `test` task - so a module missing from this list is a
+# module nobody runs before pushing. Add new KMP modules here when they gain tests.
+#
+# `./gradlew test` now reaches the KMP modules too (see the `test` alias in the root
+# build), but this hook stays explicit: a bare `test` would also pull in :desktopApp:test,
+# which needs a display server and is deliberately skipped on CLAUDE_CODE_REMOTE below.
 TASKS=(
     :quartz:jvmTest
     :commons:jvmTest
+    :commonsUI:jvmTest
     :nestsClient:jvmTest
     :quic:jvmTest
+    :marmotQuic:jvmTest
     :amethyst:testPlayDebugUnitTest
     :cli:test
 )

.github/workflows/build.yml

@@ -102,15 +102,16 @@ jobs:
 
       - name: Test + Build Desktop (gradle)
         run: |
-          CMD="./gradlew :quartz:jvmTest :commons:jvmTest :commonsUI:jvmTest :nestsClient:jvmTest :cli:test :desktopApp:test :desktopApp:${{ matrix.desktop-task }}"
+          CMD="./gradlew :quartz:jvmTest :commons:jvmTest :commonsUI:jvmTest :quic:jvmTest :nestsClient:jvmTest :marmotQuic:jvmTest :cli:test :desktopApp:test :desktopApp:${{ matrix.desktop-task }}"
           if [ "${{ runner.os }}" = "Linux" ]; then
             xvfb-run --auto-servernum $CMD
           else
             $CMD
           fi
 
-      # This job runs five test suites (:quartz, :commons, :nestsClient, :cli,
-      # :desktopApp) but, unlike test-geode / test-quartz-ios /
+      # This job runs the JVM test suites (:quartz, :commons, :commonsUI, :quic,
+      # :nestsClient, :marmotQuic, :cli, :desktopApp) but, unlike test-geode /
+      # test-quartz-ios /
       # test-and-build-android, published nothing when one of them failed. The
       # console line names the failing test and the exception class and stops
       # there, so the message is lost with the runner. That is how the

amethyst/src/main/java/com/vitorpamplona/amethyst/model/EventBroadcaster.kt

@@ -23,6 +23,7 @@ package com.vitorpamplona.amethyst.model
 import com.vitorpamplona.amethyst.commons.model.Note
 import com.vitorpamplona.amethyst.commons.model.User
 import com.vitorpamplona.amethyst.commons.model.cache.filter
+import com.vitorpamplona.quartz.nip01Core.core.Address
 import com.vitorpamplona.quartz.nip01Core.core.AddressableEvent
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
@@ -52,6 +53,19 @@ import com.vitorpamplona.quartz.nip65RelayList.AdvertisedRelayListEvent
 import com.vitorpamplona.quartz.nip78AppData.AppSpecificDataEvent
 import com.vitorpamplona.quartz.nip88Polls.poll.PollEvent
 
+/**
+ * The pubkeys an `a`-tagging event addresses, read straight from the coordinates
+ * (`kind:pubkey:dTag`) rather than from whatever the local cache happens to hold.
+ *
+ * This is what lets [EventBroadcaster] route to an addressed author's inbox relays when the
+ * addressable itself was never cached on this device - a NIP-52 RSVP being the motivating case,
+ * since its `a` tag is the only thing tying it to the appointment's host.
+ *
+ * Unparseable coordinates are dropped; the result is deduplicated because an event may address
+ * several addressables by the same author (a calendar listing its own appointments).
+ */
+fun addressedAuthors(event: AddressHintProvider): Set<HexKey> = event.linkedAddressIds().mapNotNullTo(mutableSetOf()) { Address.parse(it)?.pubKeyHex }
+
 /**
  * The sign-and-publish choke point for an [Account]: computes the relay set an
  * event should be broadcast to (NIP-65 outbox model, relay hints, channel home
@@ -232,6 +246,16 @@ class EventBroadcaster(
             event.addressHints().forEach {
                 relayList.add(it.relay)
             }
+
+            // An `a` coordinate names its own author, so the addressed user's inbox is reachable
+            // straight from the tag. Everything in the loop below is nested inside a cache
+            // lookup, so without this an event aimed at an addressable this device never cached
+            // - an RSVP to a calendar appointment that arrived as a bare reference, say - went
+            // only to the sender's own outbox and never to the author it was answering.
+            addressedAuthors(event).forEach { authorPubKey ->
+                relayList.addAll(computeRelayListForLinkedUser(authorPubKey))
+            }
+
             event.linkedAddressIds().forEach { addressId ->
                 account.cache.getAddressableNoteIfExists(addressId)?.let { linkedNote ->
                     val linkedNoteAuthor = linkedNote.author

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/note/types/CalendarRsvpRender.kt

@@ -21,16 +21,18 @@
 package com.vitorpamplona.amethyst.ui.note.types
 
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
 import com.vitorpamplona.amethyst.commons.model.Note
 import com.vitorpamplona.amethyst.commons.ui.note.CalendarRsvpCard
+import com.vitorpamplona.amethyst.service.relayClient.reqCommand.event.EventFinderFilterAssemblerSubscription
 import com.vitorpamplona.amethyst.ui.navigation.navs.INav
+import com.vitorpamplona.amethyst.ui.note.LoadAddressableNote
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.AccountViewModel
 import com.vitorpamplona.quartz.nip52Calendar.rsvp.CalendarRSVPEvent
 
 /**
- * Entry for a NIP-52 calendar RSVP: decodes the [Note] and renders the shared commons
- * [CalendarRsvpCard]. Draws only from the event's own tags, so the entry keeps the
- * dispatcher signature without touching the account or nav.
+ * Entry for a NIP-52 calendar RSVP: decodes the [Note], makes sure the appointment it answers is
+ * in the cache, and renders the shared commons [CalendarRsvpCard].
  */
 @Composable
 fun RenderCalendarRSVPEvent(
@@ -40,5 +42,40 @@ fun RenderCalendarRSVPEvent(
 ) {
     val event = note.event as? CalendarRSVPEvent ?: return
 
+    LoadAppointmentBehind(event, accountViewModel)
+
     CalendarRsvpCard(event)
 }
+
+/**
+ * Resolves the appointment this RSVP answers, from the `a` tag that is the only thing tying the
+ * two together.
+ *
+ * [LoadAddressableNote] creates the [com.vitorpamplona.amethyst.commons.model.AddressableNote] in
+ * `LocalCache` — a shell with a null event if we have never seen the appointment — and
+ * [EventFinderFilterAssemblerSubscription] then asks relays for it: `filterMissingAddressables`
+ * picks up exactly those addressables whose `event == null` and queries the address author's
+ * outbox relays plus any stored hints.
+ *
+ * Both halves matter beyond drawing this card. `EventBroadcaster` routes an RSVP by following its
+ * `a` tag into the appointment and reading the participants off it, and every step of that walk
+ * is a `LocalCache` lookup. An RSVP seen in a feed for an appointment that was never cached would
+ * otherwise leave the cache with no entry to walk, so answering it from here would reach the host
+ * (whose pubkey the coordinate carries) but none of the other invitees.
+ *
+ * Composition-scoped like every other per-note subscription: the row unsubscribes ~30s after it
+ * scrolls away or the app backgrounds.
+ */
+@Composable
+private fun LoadAppointmentBehind(
+    event: CalendarRSVPEvent,
+    accountViewModel: AccountViewModel,
+) {
+    val address = remember(event) { event.calendarEventAddress() } ?: return
+
+    LoadAddressableNote(address, accountViewModel) { appointment ->
+        if (appointment != null) {
+            EventFinderFilterAssemblerSubscription(appointment, accountViewModel)
+        }
+    }
+}

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/note/types/CalendarRsvpRow.kt

@@ -46,6 +46,7 @@ import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.AccountViewModel
 import com.vitorpamplona.quartz.nip01Core.core.Address
 import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
+import com.vitorpamplona.quartz.nip01Core.tags.events.ETag
 import com.vitorpamplona.quartz.nip01Core.tags.people.PTag
 import com.vitorpamplona.quartz.nip52Calendar.appt.tags.RSVPStatusTag
 import com.vitorpamplona.quartz.nip52Calendar.rsvp.CalendarRSVPEvent
@@ -191,14 +192,31 @@ private fun sendRsvp(
 ) {
     val relayHint = LocalCache.getNoteIfExists(eventId)?.relays?.firstOrNull()
     val aTag = ATag(targetAddress, relayHint)
+    // NIP-52's optional `e` tag: the `a` tag names the appointment's coordinate, which follows
+    // the host's edits, while this pins the exact revision the user answered. A reader can then
+    // tell an "accepted" cast against last week's time from one cast against the current one.
+    val eTag = ETag(eventId, relayHint, targetAddress.pubKeyHex)
     val pTag = PTag(targetAddress.pubKeyHex)
     val dTag = rsvpDTagFor(targetAddress)
 
+    // Only the host is p-tagged, per NIP-52 ("pubkey of the author of the calendar event being
+    // responded to"). The other invitees still receive this RSVP: EventBroadcaster follows the
+    // a-tag into the appointment and reads its participants' inbox relays from the appointment's
+    // own p tags (CalendarTimeSlotEvent/CalendarDateSlotEvent are PubKeyHintProviders).
+    //
+    // Copying those participants onto the RSVP as extra p tags would add no routing - the
+    // broadcaster's recursion and any local participant lookup read the same
+    // LocalCache.getAddressableNoteIfExists(targetAddress), so they are reachable in exactly the
+    // same cases - while giving every invitee a notification row for every other invitee's RSVP
+    // (kind 31925 is in NOTIFICATION_KINDS and tagsAnEventByUser returns true for it), bloating
+    // the signed event by a host-controlled number of tags, and muddying the spec's meaning of
+    // this kind's p tag.
     accountViewModel.launchSigner {
         accountViewModel.account.signAndComputeBroadcast(
             CalendarRSVPEvent.build(
                 calendarEventAddress = aTag,
                 status = status,
+                calendarEventId = eTag,
                 calendarEventAuthor = pTag,
                 dTag = dTag,
             ),

amethyst/src/test/java/com/vitorpamplona/amethyst/calendar/RsvpTagAssemblyTest.kt

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.calendar
+
+import com.vitorpamplona.quartz.nip01Core.core.Address
+import com.vitorpamplona.quartz.nip01Core.relay.normalizer.RelayUrlNormalizer
+import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
+import com.vitorpamplona.quartz.nip01Core.tags.events.ETag
+import com.vitorpamplona.quartz.nip01Core.tags.people.PTag
+import com.vitorpamplona.quartz.nip52Calendar.appt.tags.RSVPStatusTag
+import com.vitorpamplona.quartz.nip52Calendar.rsvp.CalendarRSVPEvent
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Locks in the tag shape [com.vitorpamplona.amethyst.ui.note.types.CalendarRsvpRow] assembles.
+ *
+ * The `p` count is the load-bearing assertion. Kind 31925 is in `NOTIFICATION_KINDS`, and
+ * `NotificationFeedFilter.tagsAnEventByUser` returns true for it (a `BaseAddressableEvent` falls
+ * through every `BaseNoteEvent` branch), so every pubkey tagged here gets a notification row for
+ * this RSVP. Tagging the appointment's other invitees would therefore hand each of them one row
+ * per co-invitee per answer change, and buys no routing: `EventBroadcaster` already reaches them
+ * by following the a-tag into the appointment, whose own p tags it reads as pubkey hints.
+ */
+class RsvpTagAssemblyTest {
+    private val host = "460c25e682fda7832b52d1f22d3d22b3176d972f60dcdc3212ed8c92ef85065c"
+    private val apptId = "43575072239da152afe3d7b5c70ed2beb48db2b10e60c60da45229c09c877d2a"
+    private val relay = "wss://relay.damus.io/"
+
+    private fun buildRsvp(): Array<Array<String>> {
+        val target = Address(31923, host, "party")
+        val hint = RelayUrlNormalizer.normalizeOrNull(relay)
+
+        return CalendarRSVPEvent
+            .build(
+                calendarEventAddress = ATag(target, hint),
+                status = RSVPStatusTag.STATUS.ACCEPTED,
+                calendarEventId = ETag(apptId, hint, host),
+                calendarEventAuthor = PTag(host),
+                dTag = "rsvp-d",
+            ).tags
+    }
+
+    @Test
+    fun tagsTheAppointmentCoordinateAndThePinnedRevision() {
+        val tags = buildRsvp()
+
+        // The `a` tag follows the host's later edits; the `e` tag pins the revision answered.
+        assertEquals("31923:$host:party", tags.single { it[0] == "a" }[1])
+        assertEquals(apptId, tags.single { it[0] == "e" }[1])
+        assertEquals("rsvp-d", tags.single { it[0] == "d" }[1])
+        assertEquals("accepted", tags.single { it[0] == "status" }[1])
+    }
+
+    @Test
+    fun tagsExactlyOnePubkeyAndItIsTheHost() {
+        val pTags = buildRsvp().filter { it[0] == "p" }
+
+        assertEquals(listOf(host), pTags.map { it[1] })
+    }
+
+    @Test
+    fun theHostRemainsTheFirstPubkeySoCalendarEventAuthorResolves() {
+        val tags = buildRsvp()
+        val event =
+            CalendarRSVPEvent(
+                id = "00".repeat(32),
+                pubKey = "11".repeat(32),
+                createdAt = 1700000000,
+                tags = tags,
+                content = "",
+                sig = "00".repeat(64),
+            )
+
+        assertEquals(host, event.calendarEventAuthor()?.pubKey)
+        assertEquals(apptId, event.calendarEventId()?.eventId)
+    }
+}

amethyst/src/test/java/com/vitorpamplona/amethyst/model/AddressedAuthorRoutingTest.kt

@@ -0,0 +1,125 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.amethyst.model
+
+import com.vitorpamplona.quartz.nip52Calendar.calendar.CalendarEvent
+import com.vitorpamplona.quartz.nip52Calendar.rsvp.CalendarRSVPEvent
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * [addressedAuthors] is what lets [EventBroadcaster] reach an addressed author's inbox relays
+ * without a cache hit. The rest of the a-tag branch is nested inside
+ * `getAddressableNoteIfExists(addressId)`, so before this existed an RSVP answering an
+ * appointment this device had never cached went only to the sender's own outbox — the host it
+ * was replying to never received it.
+ */
+class AddressedAuthorRoutingTest {
+    private val host = "460c25e682fda7832b52d1f22d3d22b3176d972f60dcdc3212ed8c92ef85065c"
+    private val other = "99bb5591c9116600f845107d31f9b59e2f7c7e09a1ff802e84f1d43da557ca64"
+    private val relay = "wss://relay.damus.io/"
+
+    private fun rsvp(vararg tags: Array<String>) =
+        CalendarRSVPEvent(
+            id = "00".repeat(32),
+            pubKey = "11".repeat(32),
+            createdAt = 1700000000,
+            tags = arrayOf(*tags),
+            content = "",
+            sig = "00".repeat(64),
+        )
+
+    private fun calendar(vararg tags: Array<String>) =
+        CalendarEvent(
+            id = "22".repeat(32),
+            pubKey = host,
+            createdAt = 1700000000,
+            tags = arrayOf(*tags),
+            content = "",
+            sig = "00".repeat(64),
+        )
+
+    @Test
+    fun `an RSVP addresses the appointment's host`() {
+        val event = rsvp(arrayOf("a", "31923:$host:party", relay), arrayOf("status", "accepted"))
+
+        assertEquals(setOf(host), addressedAuthors(event))
+    }
+
+    @Test
+    fun `the host is found without a relay hint on the tag`() {
+        // The hint is optional; the coordinate alone must still identify who to deliver to.
+        val event = rsvp(arrayOf("a", "31923:$host:party"), arrayOf("status", "declined"))
+
+        assertEquals(setOf(host), addressedAuthors(event))
+    }
+
+    @Test
+    fun `a day-slot appointment resolves the same way`() {
+        val event = rsvp(arrayOf("a", "31922:$host:all-day"), arrayOf("status", "tentative"))
+
+        assertEquals(setOf(host), addressedAuthors(event))
+    }
+
+    @Test
+    fun `a calendar addresses every appointment author it lists`() {
+        val event =
+            calendar(
+                arrayOf("d", "my-calendar"),
+                arrayOf("a", "31923:$host:party", relay),
+                arrayOf("a", "31922:$other:standup"),
+            )
+
+        assertEquals(setOf(host, other), addressedAuthors(event))
+    }
+
+    @Test
+    fun `repeated authors collapse to one delivery target`() {
+        // A calendar usually lists many appointments by the same host; their inbox is one target.
+        val event =
+            calendar(
+                arrayOf("d", "my-calendar"),
+                arrayOf("a", "31923:$host:party"),
+                arrayOf("a", "31923:$host:standup"),
+                arrayOf("a", "31922:$host:all-day"),
+            )
+
+        assertEquals(setOf(host), addressedAuthors(event))
+    }
+
+    @Test
+    fun `a malformed coordinate is dropped rather than throwing`() {
+        val event =
+            rsvp(
+                arrayOf("a", "not-a-coordinate"),
+                arrayOf("a", "31923:$host:party"),
+                arrayOf("status", "accepted"),
+            )
+
+        assertEquals(setOf(host), addressedAuthors(event))
+    }
+
+    @Test
+    fun `an event with no a tags addresses nobody`() {
+        assertTrue(addressedAuthors(rsvp(arrayOf("status", "accepted"))).isEmpty())
+    }
+}

build.gradle.kts

@@ -96,6 +96,36 @@ allprojects {
 
 subprojects {
     afterEvaluate {
+        // The Kotlin Multiplatform plugin never registers a plain `test` task: it creates one
+        // task per target (jvmTest, androidUnitTest, linuxX64Test, ...) plus the `allTests`
+        // aggregate. A root `./gradlew test` therefore runs `test` only in the Java/Android
+        // modules that own one and *silently* skips every KMP module - Gradle only errors when
+        // no project at all has the task, and four of them do, so it exits 0 looking healthy.
+        // That hid ~8k tests (quartz, commons, commonsUI, quic, nestsClient, marmotQuic), which
+        // is most of this repo's suite. Register the alias so the documented command means what
+        // it says.
+        //
+        // It maps to jvmTest, not allTests, on purpose: allTests also drags in androidUnitTest
+        // and the native targets, half of which cannot run on a given host (macosArm64Test on
+        // Linux) and all of which change what `test` costs. jvmTest is exactly what the
+        // pre-push hook and CI already run for these modules, so the alias matches the coverage
+        // they expect rather than inventing a third definition of "the tests".
+        //
+        // The flip side: a KMP module's non-JVM targets stay outside `test`. :quartz's
+        // androidHostTest source set (~3.9k tests) is the big one - nothing runs it today and it
+        // is red on main, so aliasing onto allTests would have turned `test` red for everyone
+        // rather than fixing anything. Tracked in CLAUDE.md's Build Commands section.
+        if (plugins.hasPlugin("org.jetbrains.kotlin.multiplatform") &&
+            tasks.findByName("test") == null &&
+            tasks.findByName("jvmTest") != null
+        ) {
+            tasks.register("test") {
+                group = "verification"
+                description = "Runs the JVM unit tests for this Kotlin Multiplatform module."
+                dependsOn("jvmTest")
+            }
+        }
+
         try {
             tasks.named("preBuild") {
                 dependsOn("spotlessApply")

quartz/src/androidUnitTest/kotlin/com/vitorpamplona/quartz/TestResourceLoader.kt

@@ -1,30 +0,0 @@
-/*
- * Copyright (c) 2025 Vitor Pamplona
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of
- * this software and associated documentation files (the "Software"), to deal in
- * the Software without restriction, including without limitation the rights to use,
- * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
- * Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
- * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
- * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
- * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
- * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- */
-package com.vitorpamplona.quartz
-
-actual class TestResourceLoader {
-    actual fun loadString(file: String): String =
-        this@TestResourceLoader
-            .javaClass.classLoader!!
-            .getResourceAsStream(file)
-            .bufferedReader()
-            .use { it.readText() }
-}

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip52Calendar/appt/day/CalendarDateSlotEvent.kt

@@ -25,6 +25,7 @@ import com.vitorpamplona.quartz.nip01Core.core.BaseAddressableEvent
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
 import com.vitorpamplona.quartz.nip01Core.core.firstTagValue
+import com.vitorpamplona.quartz.nip01Core.hints.PubKeyHintProvider
 import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
 import com.vitorpamplona.quartz.nip01Core.tags.dTag.dTag
 import com.vitorpamplona.quartz.nip01Core.tags.geohash.GeoHashTag
@@ -50,6 +51,7 @@ class CalendarDateSlotEvent(
     content: String,
     sig: HexKey,
 ) : BaseAddressableEvent(id, pubKey, createdAt, KIND, tags, content, sig),
+    PubKeyHintProvider,
     SearchableEvent {
     override fun indexableContent() = listOfNotNull(title(), summary(), content).joinToString("\n")
 
@@ -81,6 +83,13 @@ class CalendarDateSlotEvent(
 
     fun participants() = tags.mapNotNull(PTag.Companion::parse)
 
+    // NIP-52 `p` tags are the invitees/hosts of this appointment. Exposing them as pubkey
+    // hints lets the broadcaster route the appointment - and anything that a-tags it, like an
+    // RSVP - into every participant's inbox relays instead of just the author's outbox.
+    override fun pubKeyHints() = tags.mapNotNull(PTag::parseAsHint)
+
+    override fun linkedPubKeys() = tags.mapNotNull(PTag::parseKey)
+
     fun references() = tags.references()
 
     companion object {

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip52Calendar/appt/time/CalendarTimeSlotEvent.kt

@@ -26,6 +26,7 @@ import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
 import com.vitorpamplona.quartz.nip01Core.core.firstTagValue
 import com.vitorpamplona.quartz.nip01Core.core.firstTagValueAsLong
+import com.vitorpamplona.quartz.nip01Core.hints.PubKeyHintProvider
 import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
 import com.vitorpamplona.quartz.nip01Core.tags.dTag.dTag
 import com.vitorpamplona.quartz.nip01Core.tags.geohash.GeoHashTag
@@ -52,6 +53,7 @@ class CalendarTimeSlotEvent(
     content: String,
     sig: HexKey,
 ) : BaseAddressableEvent(id, pubKey, createdAt, KIND, tags, content, sig),
+    PubKeyHintProvider,
     SearchableEvent {
     override fun indexableContent() = listOfNotNull(title(), summary(), content).joinToString("\n")
 
@@ -90,6 +92,13 @@ class CalendarTimeSlotEvent(
 
     fun participants() = tags.mapNotNull(PTag.Companion::parse)
 
+    // NIP-52 `p` tags are the invitees/hosts of this appointment. Exposing them as pubkey
+    // hints lets the broadcaster route the appointment - and anything that a-tags it, like an
+    // RSVP - into every participant's inbox relays instead of just the author's outbox.
+    override fun pubKeyHints() = tags.mapNotNull(PTag::parseAsHint)
+
+    override fun linkedPubKeys() = tags.mapNotNull(PTag::parseKey)
+
     fun references() = tags.references()
 
     companion object {

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip52Calendar/calendar/CalendarEvent.kt

@@ -24,7 +24,9 @@ import androidx.compose.runtime.Immutable
 import com.vitorpamplona.quartz.nip01Core.core.BaseAddressableEvent
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+import com.vitorpamplona.quartz.nip01Core.hints.AddressHintProvider
 import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
+import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
 import com.vitorpamplona.quartz.nip01Core.tags.aTag.taggedAddresses
 import com.vitorpamplona.quartz.nip01Core.tags.dTag.dTag
 import com.vitorpamplona.quartz.nip23LongContent.tags.TitleTag
@@ -43,6 +45,7 @@ class CalendarEvent(
     content: String,
     sig: HexKey,
 ) : BaseAddressableEvent(id, pubKey, createdAt, KIND, tags, content, sig),
+    AddressHintProvider,
     SearchableEvent {
     override fun indexableContent() = listOfNotNull(title(), content).joinToString("\n")
 
@@ -57,6 +60,13 @@ class CalendarEvent(
 
     fun calendarEventAddresses() = taggedAddresses()
 
+    // A calendar is a list of `a` tags pointing at the appointments it collects. Surfacing them
+    // lets the broadcaster route a published calendar to the relays those appointments live on,
+    // and lets the hint index learn the calendar -> appointment links.
+    override fun addressHints() = tags.mapNotNull(ATag::parseAsHint)
+
+    override fun linkedAddressIds() = tags.mapNotNull(ATag::parseAddressId)
+
     companion object {
         const val KIND = 31924
 

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip52Calendar/rsvp/CalendarRSVPEvent.kt

@@ -24,6 +24,8 @@ import androidx.compose.runtime.Immutable
 import com.vitorpamplona.quartz.nip01Core.core.BaseAddressableEvent
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.core.TagArrayBuilder
+import com.vitorpamplona.quartz.nip01Core.hints.AddressHintProvider
+import com.vitorpamplona.quartz.nip01Core.hints.EventHintProvider
 import com.vitorpamplona.quartz.nip01Core.hints.PubKeyHintProvider
 import com.vitorpamplona.quartz.nip01Core.signers.eventTemplate
 import com.vitorpamplona.quartz.nip01Core.tags.aTag.ATag
@@ -51,6 +53,8 @@ class CalendarRSVPEvent(
     sig: HexKey,
 ) : BaseAddressableEvent(id, pubKey, createdAt, KIND, tags, content, sig),
     PubKeyHintProvider,
+    AddressHintProvider,
+    EventHintProvider,
     SearchableEvent {
     override fun indexableContent() = content
 
@@ -64,6 +68,16 @@ class CalendarRSVPEvent(
 
     override fun linkedPubKeys() = tags.mapNotNull(PTag::parseKey)
 
+    override fun addressHints() = tags.mapNotNull(ATag::parseAsHint)
+
+    override fun linkedAddressIds() = tags.mapNotNull(ATag::parseAddressId)
+
+    // NIP-52's optional `e` tag pins the exact appointment revision this RSVP answered, next to
+    // the `a` tag's coordinate. Routing on it as well reaches whoever served that revision.
+    override fun eventHints() = tags.mapNotNull(ETag::parseAsHint)
+
+    override fun linkedEventIds() = tags.mapNotNull(ETag::parseId)
+
     fun status() = tags.firstNotNullOfOrNull(RSVPStatusTag.Companion::parse)
 
     fun statusValue() = tags.firstNotNullOfOrNull(RSVPStatusTag.Companion::parseValue)

quartz/src/commonTest/kotlin/com/vitorpamplona/quartz/nip52Calendar/CalendarHintProviderTest.kt

@@ -0,0 +1,180 @@
+/*
+ * Copyright (c) 2025 Vitor Pamplona
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+ * Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.vitorpamplona.quartz.nip52Calendar
+
+import com.vitorpamplona.quartz.nip01Core.hints.AddressHintProvider
+import com.vitorpamplona.quartz.nip01Core.hints.EventHintProvider
+import com.vitorpamplona.quartz.nip01Core.hints.PubKeyHintProvider
+import com.vitorpamplona.quartz.nip01Core.relay.normalizer.RelayUrlNormalizer
+import com.vitorpamplona.quartz.nip52Calendar.appt.day.CalendarDateSlotEvent
+import com.vitorpamplona.quartz.nip52Calendar.appt.time.CalendarTimeSlotEvent
+import com.vitorpamplona.quartz.nip52Calendar.calendar.CalendarEvent
+import com.vitorpamplona.quartz.nip52Calendar.rsvp.CalendarRSVPEvent
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+/**
+ * The broadcaster (EventBroadcaster) resolves a published event's relay set from these two
+ * interfaces: `p` tags become inbox relays of everyone tagged, `a` tags get followed into the
+ * referenced addressable and recursed. Without them an RSVP reaches only the sender's outbox.
+ */
+class CalendarHintProviderTest {
+    private val host = "460c25e682fda7832b52d1f22d3d22b3176d972f60dcdc3212ed8c92ef85065c"
+    private val invitee = "99bb5591c9116600f845107d31f9b59e2f7c7e09a1ff802e84f1d43da557ca64"
+    private val rsvper = "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"
+    private val apptAddress = "31923:$host:my-party"
+    private val apptId = "43575072239da152afe3d7b5c70ed2beb48db2b10e60c60da45229c09c877d2a"
+    private val relay = "wss://relay.damus.io/"
+
+    private fun rsvp(vararg tags: Array<String>) =
+        CalendarRSVPEvent(
+            id = "00".repeat(32),
+            pubKey = rsvper,
+            createdAt = 1700000000,
+            tags = arrayOf(*tags),
+            content = "",
+            sig = "00".repeat(64),
+        )
+
+    private fun timeSlot(vararg tags: Array<String>) =
+        CalendarTimeSlotEvent(
+            id = "11".repeat(32),
+            pubKey = host,
+            createdAt = 1700000000,
+            tags = arrayOf(*tags),
+            content = "",
+            sig = "00".repeat(64),
+        )
+
+    private fun calendar(vararg tags: Array<String>) =
+        CalendarEvent(
+            id = "33".repeat(32),
+            pubKey = host,
+            createdAt = 1700000000,
+            tags = arrayOf(*tags),
+            content = "",
+            sig = "00".repeat(64),
+        )
+
+    private fun dateSlot(vararg tags: Array<String>) =
+        CalendarDateSlotEvent(
+            id = "22".repeat(32),
+            pubKey = host,
+            createdAt = 1700000000,
+            tags = arrayOf(*tags),
+            content = "",
+            sig = "00".repeat(64),
+        )
+
+    @Test
+    fun rsvpExposesTheTargetAppointmentAsALinkedAddress() {
+        val event = rsvp(arrayOf("a", apptAddress, relay), arrayOf("status", "accepted"))
+
+        // Typed, not `is`: the point is that the class declares the interface at compile time.
+        val provider: AddressHintProvider = event
+        assertEquals(listOf(apptAddress), provider.linkedAddressIds())
+
+        val hint = provider.addressHints().single()
+        assertEquals(apptAddress, hint.addressId)
+        assertEquals(RelayUrlNormalizer.normalizeOrNull(relay), hint.relay)
+    }
+
+    @Test
+    fun rsvpWithoutARelayHintStillLinksTheAddress() {
+        val event = rsvp(arrayOf("a", apptAddress), arrayOf("status", "accepted"))
+
+        assertEquals(listOf(apptAddress), event.linkedAddressIds())
+        assertTrue(event.addressHints().isEmpty())
+    }
+
+    @Test
+    fun rsvpLinksEveryTaggedParticipantNotJustTheHost() {
+        val event =
+            rsvp(
+                arrayOf("a", apptAddress, relay),
+                arrayOf("p", host),
+                arrayOf("p", invitee, relay),
+                arrayOf("status", "accepted"),
+            )
+
+        assertEquals(listOf(host, invitee), event.linkedPubKeys())
+        assertEquals(listOf(invitee), event.pubKeyHints().map { it.pubkey })
+    }
+
+    @Test
+    fun timeSlotExposesParticipantsAsLinkedPubKeys() {
+        val event = timeSlot(arrayOf("d", "my-party"), arrayOf("p", invitee, relay, "speaker"))
+
+        val provider: PubKeyHintProvider = event
+        assertEquals(listOf(invitee), provider.linkedPubKeys())
+
+        val hint = provider.pubKeyHints().single()
+        assertEquals(invitee, hint.pubkey)
+        assertEquals(RelayUrlNormalizer.normalizeOrNull(relay), hint.relay)
+    }
+
+    @Test
+    fun dateSlotExposesParticipantsAsLinkedPubKeys() {
+        val event = dateSlot(arrayOf("d", "my-party"), arrayOf("p", invitee, relay, "speaker"))
+
+        val provider: PubKeyHintProvider = event
+        assertEquals(listOf(invitee), provider.linkedPubKeys())
+        assertEquals(invitee, provider.pubKeyHints().single().pubkey)
+    }
+
+    @Test
+    fun rsvpExposesTheOptionalETagAsALinkedEvent() {
+        // NIP-52's `e` tag pins the exact appointment revision the RSVP answered; the `a` tag
+        // alone follows the host's later edits.
+        val event =
+            rsvp(
+                arrayOf("a", apptAddress, relay),
+                arrayOf("e", apptId, relay, host),
+                arrayOf("status", "accepted"),
+            )
+
+        val provider: EventHintProvider = event
+        assertEquals(listOf(apptId), provider.linkedEventIds())
+
+        val hint = provider.eventHints().single()
+        assertEquals(apptId, hint.eventId)
+        assertEquals(RelayUrlNormalizer.normalizeOrNull(relay), hint.relay)
+    }
+
+    @Test
+    fun rsvpWithoutAnETagLinksNoEvents() {
+        val event = rsvp(arrayOf("a", apptAddress, relay), arrayOf("status", "accepted"))
+
+        assertTrue(event.linkedEventIds().isEmpty())
+        assertTrue(event.eventHints().isEmpty())
+    }
+
+    @Test
+    fun calendarExposesItsAppointmentsAsLinkedAddresses() {
+        val other = "31922:$invitee:standup"
+        val event = calendar(arrayOf("d", "my-calendar"), arrayOf("a", apptAddress, relay), arrayOf("a", other))
+
+        val provider: AddressHintProvider = event
+        assertEquals(listOf(apptAddress, other), provider.linkedAddressIds())
+        assertEquals(apptAddress, provider.addressHints().single().addressId)
+    }
+}