feat: add reminder source (#126)

packages/freya-source-reminders/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@freya/source-reminders",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test src/"
+	},
+	"dependencies": {
+		"@freya/components": "workspace:*",
+		"@freya/core": "workspace:*",
+		"arktype": "^2.1.0"
+	},
+	"peerDependencies": {
+		"@json-render/core": "*",
+		"@nym.sh/jrx": "*"
+	}
+}

packages/freya-source-reminders/src/index.ts

@@ -0,0 +1,11 @@
+export { ReminderSource, type ReminderSourceOptions } from "./reminder-source.ts"
+export {
+	createReminderOccurrenceId,
+	expandReminderOccurrences,
+	expandReminderOriginalDueAts,
+	findReminderOccurrenceIndex,
+	recurrenceAfterSplit,
+	stopRecurrenceAfterOccurrenceCount,
+} from "./recurrence.ts"
+export { renderReminderFeedItem } from "./renderer.tsx"
+export * from "./types.ts"

packages/freya-source-reminders/src/recurrence.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test"
+
+import type { Reminder } from "./types.ts"
+
+import { expandReminderOriginalDueAts, findReminderOccurrenceIndex } from "./recurrence.ts"
+import { ReminderPriority, ReminderRecurrenceFrequency, ReminderWeekday } from "./types.ts"
+
+describe("recurrence", () => {
+	test("deduplicates weekly weekdays before applying recurrence count", () => {
+		const reminder = weeklyReminder({
+			recurrence: {
+				frequency: ReminderRecurrenceFrequency.Weekly,
+				interval: 1,
+				weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+				count: 3,
+			},
+		})
+
+		const originalDueAts = expandReminderOriginalDueAts(
+			reminder,
+			new Date("2026-06-08T00:00:00Z"),
+			new Date("2026-06-22T00:00:00Z"),
+		)
+
+		expect(originalDueAts.map(toIsoString)).toEqual([
+			"2026-06-08T09:00:00.000Z",
+			"2026-06-10T09:00:00.000Z",
+			"2026-06-15T09:00:00.000Z",
+		])
+	})
+
+	test("deduplicates weekly weekdays before calculating occurrence indexes", () => {
+		const reminder = weeklyReminder({
+			recurrence: {
+				frequency: ReminderRecurrenceFrequency.Weekly,
+				interval: 1,
+				weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+			},
+		})
+
+		expect(findReminderOccurrenceIndex(reminder, new Date("2026-06-10T09:00:00Z"))).toBe(1)
+		expect(findReminderOccurrenceIndex(reminder, new Date("2026-06-15T09:00:00Z"))).toBe(2)
+	})
+})
+
+function weeklyReminder(overrides: Partial<Reminder> = {}): Reminder {
+	const now = new Date("2026-06-01T00:00:00Z")
+	return {
+		id: "r1",
+		title: "Take vitamins",
+		notes: null,
+		dueAt: new Date("2026-06-08T09:00:00Z"),
+		timeZone: "UTC",
+		recurrence: {
+			frequency: ReminderRecurrenceFrequency.Weekly,
+			interval: 1,
+			weekdays: [ReminderWeekday.Monday],
+		},
+		priority: ReminderPriority.Normal,
+		createdAt: now,
+		updatedAt: now,
+		...overrides,
+	}
+}
+
+function toIsoString(date: Date): string {
+	return date.toISOString()
+}

packages/freya-source-reminders/src/recurrence.ts

@@ -0,0 +1,392 @@
+import type {
+	Reminder,
+	ReminderOccurrence,
+	ReminderOccurrenceOverride,
+	ReminderOccurrencePatch,
+	ReminderRecurrence,
+	ReminderWeekday,
+} from "./types.ts"
+
+import { ReminderRecurrenceFrequency } from "./types.ts"
+
+interface ZonedDateTimeParts {
+	year: number
+	month: number
+	day: number
+	hour: number
+	minute: number
+	second: number
+	millisecond: number
+}
+
+interface ExpandReminderOccurrencesOptions {
+	from: Date
+	to: Date
+	includeCompleted: boolean
+	overrides?: readonly ReminderOccurrenceOverride[]
+}
+
+export function createReminderOccurrenceId(originalDueAt: Date): string {
+	return originalDueAt.toISOString()
+}
+
+export function expandReminderOccurrences(
+	reminder: Reminder,
+	options: ExpandReminderOccurrencesOptions,
+): ReminderOccurrence[] {
+	const originalDueAts = new Map<string, Date>()
+	for (const dueAt of expandReminderOriginalDueAts(reminder, options.from, options.to)) {
+		originalDueAts.set(createReminderOccurrenceId(dueAt), dueAt)
+	}
+
+	const overrideById = new Map<string, ReminderOccurrenceOverride>()
+	for (const override of options.overrides ?? []) {
+		if (override.reminderId !== reminder.id) continue
+		if (!isCurrentOriginalDueAt(reminder, override.originalDueAt)) continue
+		overrideById.set(override.occurrenceId, override)
+		originalDueAts.set(override.occurrenceId, override.originalDueAt)
+	}
+
+	const occurrences: ReminderOccurrence[] = []
+	const originals = Array.from(originalDueAts.values()).sort(compareDates)
+
+	for (const originalDueAt of originals) {
+		const occurrenceId = createReminderOccurrenceId(originalDueAt)
+		const override = overrideById.get(occurrenceId)
+		if (override?.deletedAt) continue
+
+		const occurrence = createOccurrence(reminder, originalDueAt, override)
+		if (occurrence.dueAt < options.from || occurrence.dueAt > options.to) continue
+		if (!options.includeCompleted && occurrence.completedAt) continue
+
+		occurrences.push(occurrence)
+	}
+
+	return occurrences.sort(compareOccurrences)
+}
+
+export function expandReminderOriginalDueAts(reminder: Reminder, from: Date, to: Date): Date[] {
+	if (to < reminder.dueAt) return []
+
+	if (!reminder.recurrence) {
+		return reminder.dueAt >= from && reminder.dueAt <= to ? [reminder.dueAt] : []
+	}
+
+	switch (reminder.recurrence.frequency) {
+		case ReminderRecurrenceFrequency.Daily:
+			return expandDaily(reminder, from, to)
+		case ReminderRecurrenceFrequency.Weekly:
+			return expandWeekly(reminder, from, to)
+		case ReminderRecurrenceFrequency.Monthly:
+			return expandMonthly(reminder, from, to)
+		case ReminderRecurrenceFrequency.Yearly:
+			return expandYearly(reminder, from, to)
+	}
+}
+
+export function findReminderOccurrenceIndex(
+	reminder: Reminder,
+	occurrenceDueAt: Date,
+): number | null {
+	if (!reminder.recurrence) {
+		return reminder.dueAt.getTime() === occurrenceDueAt.getTime() ? 0 : null
+	}
+
+	const originals = expandReminderOriginalDueAts(reminder, reminder.dueAt, occurrenceDueAt)
+	for (let index = 0; index < originals.length; index++) {
+		if (originals[index]!.getTime() === occurrenceDueAt.getTime()) {
+			return index
+		}
+	}
+
+	return null
+}
+
+function isCurrentOriginalDueAt(reminder: Reminder, originalDueAt: Date): boolean {
+	return findReminderOccurrenceIndex(reminder, originalDueAt) !== null
+}
+
+export function stopRecurrenceAfterOccurrenceCount(
+	recurrence: ReminderRecurrence,
+	count: number,
+): ReminderRecurrence | null {
+	if (count <= 0) return null
+	return { ...recurrence, count }
+}
+
+export function recurrenceAfterSplit(
+	recurrence: ReminderRecurrence,
+	occurrenceIndex: number,
+): ReminderRecurrence | null {
+	if (recurrence.count === undefined) {
+		return { ...recurrence }
+	}
+
+	const remainingCount = recurrence.count - occurrenceIndex
+	if (remainingCount <= 1) return null
+
+	return { ...recurrence, count: remainingCount }
+}
+
+function expandDaily(reminder: Reminder, from: Date, to: Date): Date[] {
+	return expandStepped(reminder, from, to, function addDaily(parts, step) {
+		return addDays(parts, step)
+	})
+}
+
+function expandMonthly(reminder: Reminder, from: Date, to: Date): Date[] {
+	const anchor = getZonedParts(reminder.dueAt, reminder.timeZone).day
+	return expandStepped(reminder, from, to, function addMonthly(parts, step) {
+		return addMonths(parts, step, anchor)
+	})
+}
+
+function expandYearly(reminder: Reminder, from: Date, to: Date): Date[] {
+	const anchor = getZonedParts(reminder.dueAt, reminder.timeZone).day
+	return expandStepped(reminder, from, to, function addYearly(parts, step) {
+		return addMonths(parts, step * 12, anchor)
+	})
+}
+
+function expandStepped(
+	reminder: Reminder,
+	from: Date,
+	to: Date,
+	addStep: (parts: ZonedDateTimeParts, step: number) => ZonedDateTimeParts,
+): Date[] {
+	const recurrence = reminder.recurrence
+	if (!recurrence) return []
+
+	const dates: Date[] = []
+	const start = getZonedParts(reminder.dueAt, reminder.timeZone)
+	let emitted = 0
+	let index = 0
+
+	while (true) {
+		const parts = addStep(start, index * recurrence.interval)
+		const dueAt = zonedPartsToDate(parts, reminder.timeZone)
+		if (isAfterRecurrenceEnd(dueAt, recurrence, emitted)) break
+		if (dueAt > to) break
+
+		if (dueAt >= from) {
+			dates.push(dueAt)
+		}
+
+		emitted++
+		index++
+	}
+
+	return dates
+}
+
+function expandWeekly(reminder: Reminder, from: Date, to: Date): Date[] {
+	const recurrence = reminder.recurrence
+	if (!recurrence) return []
+
+	const start = getZonedParts(reminder.dueAt, reminder.timeZone)
+	const startWeekday = weekdayForParts(start)
+	const weekStart = addDays(start, -startWeekday)
+	const weekdays = recurrence.weekdays?.length
+		? Array.from(new Set(recurrence.weekdays)).sort(compareNumbers)
+		: [startWeekday as ReminderWeekday]
+
+	const dates: Date[] = []
+	let emitted = 0
+	let weekIndex = 0
+
+	while (true) {
+		let weekHadFutureDate = false
+
+		for (const weekday of weekdays) {
+			const parts = addDays(weekStart, weekIndex * recurrence.interval * 7 + weekday)
+			const dueAt = zonedPartsToDate(parts, reminder.timeZone)
+			if (dueAt < reminder.dueAt) continue
+			if (isAfterRecurrenceEnd(dueAt, recurrence, emitted)) return dates
+			if (dueAt > to) {
+				weekHadFutureDate = true
+				continue
+			}
+
+			if (dueAt >= from) {
+				dates.push(dueAt)
+			}
+
+			emitted++
+		}
+
+		if (weekHadFutureDate) break
+		weekIndex++
+	}
+
+	return dates.sort(compareDates)
+}
+
+function createOccurrence(
+	reminder: Reminder,
+	originalDueAt: Date,
+	override: ReminderOccurrenceOverride | undefined,
+): ReminderOccurrence {
+	const patch = override?.patch
+
+	return {
+		reminderId: reminder.id,
+		occurrenceId: createReminderOccurrenceId(originalDueAt),
+		title: patch?.title ?? reminder.title,
+		notes: valueWithNullableOverride(reminder.notes, patch, "notes"),
+		originalDueAt,
+		dueAt: patch?.dueAt ?? originalDueAt,
+		timeZone: patch?.timeZone ?? reminder.timeZone,
+		recurrence: reminder.recurrence,
+		priority: patch?.priority ?? reminder.priority,
+		completedAt: override?.completedAt ?? null,
+	}
+}
+
+function valueWithNullableOverride(
+	fallback: string | null,
+	patch: ReminderOccurrencePatch | undefined,
+	key: "notes",
+): string | null {
+	if (!patch) return fallback
+	if (Object.prototype.hasOwnProperty.call(patch, key)) {
+		return patch[key] ?? null
+	}
+	return fallback
+}
+
+function isAfterRecurrenceEnd(
+	dueAt: Date,
+	recurrence: ReminderRecurrence,
+	emittedCount: number,
+): boolean {
+	if (recurrence.count !== undefined && emittedCount >= recurrence.count) {
+		return true
+	}
+	if (recurrence.until !== undefined && dueAt > recurrence.until) {
+		return true
+	}
+	return false
+}
+
+function getZonedParts(date: Date, timeZone: string): ZonedDateTimeParts {
+	const formatter = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hourCycle: "h23",
+	})
+
+	const parts = formatter.formatToParts(date)
+	return {
+		year: numberPart(parts, "year"),
+		month: numberPart(parts, "month"),
+		day: numberPart(parts, "day"),
+		hour: numberPart(parts, "hour"),
+		minute: numberPart(parts, "minute"),
+		second: numberPart(parts, "second"),
+		millisecond: date.getUTCMilliseconds(),
+	}
+}
+
+function zonedPartsToDate(parts: ZonedDateTimeParts, timeZone: string): Date {
+	const localAsUtc = Date.UTC(
+		parts.year,
+		parts.month - 1,
+		parts.day,
+		parts.hour,
+		parts.minute,
+		parts.second,
+		parts.millisecond,
+	)
+	let timestamp = localAsUtc
+
+	for (let i = 0; i < 3; i++) {
+		const offset = getTimeZoneOffsetMs(new Date(timestamp), timeZone)
+		const next = localAsUtc - offset
+		if (next === timestamp) break
+		timestamp = next
+	}
+
+	return new Date(timestamp)
+}
+
+function getTimeZoneOffsetMs(date: Date, timeZone: string): number {
+	const parts = getZonedParts(date, timeZone)
+	const zonedAsUtc = Date.UTC(
+		parts.year,
+		parts.month - 1,
+		parts.day,
+		parts.hour,
+		parts.minute,
+		parts.second,
+		parts.millisecond,
+	)
+
+	return zonedAsUtc - date.getTime()
+}
+
+function numberPart(parts: Intl.DateTimeFormatPart[], type: Intl.DateTimeFormatPartTypes): number {
+	const part = parts.find(function matchesType(value) {
+		return value.type === type
+	})
+	if (!part) {
+		throw new Error(`Missing ${type} part while formatting zoned date`)
+	}
+	return Number(part.value)
+}
+
+function addDays(parts: ZonedDateTimeParts, days: number): ZonedDateTimeParts {
+	const date = new Date(Date.UTC(parts.year, parts.month - 1, parts.day + days))
+	return {
+		...parts,
+		year: date.getUTCFullYear(),
+		month: date.getUTCMonth() + 1,
+		day: date.getUTCDate(),
+	}
+}
+
+function addMonths(
+	parts: ZonedDateTimeParts,
+	months: number,
+	anchorDay: number,
+): ZonedDateTimeParts {
+	const monthIndex = parts.year * 12 + parts.month - 1 + months
+	const year = Math.floor(monthIndex / 12)
+	const month = positiveModulo(monthIndex, 12) + 1
+	const day = Math.min(anchorDay, daysInMonth(year, month))
+
+	return {
+		...parts,
+		year,
+		month,
+		day,
+	}
+}
+
+function daysInMonth(year: number, month: number): number {
+	return new Date(Date.UTC(year, month, 0)).getUTCDate()
+}
+
+function weekdayForParts(parts: ZonedDateTimeParts): number {
+	return new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay()
+}
+
+function positiveModulo(value: number, divisor: number): number {
+	return ((value % divisor) + divisor) % divisor
+}
+
+function compareDates(a: Date, b: Date): number {
+	return a.getTime() - b.getTime()
+}
+
+function compareNumbers(a: number, b: number): number {
+	return a - b
+}
+
+function compareOccurrences(a: ReminderOccurrence, b: ReminderOccurrence): number {
+	return a.dueAt.getTime() - b.dueAt.getTime()
+}

packages/freya-source-reminders/src/reminder-source.test.ts

@@ -0,0 +1,706 @@
+import { Context, TimeRelevance } from "@freya/core"
+import { describe, expect, mock, test } from "bun:test"
+
+import type {
+	CreateReminderInput,
+	Reminder,
+	ReminderListParams,
+	ReminderOccurrenceOverride,
+	ReminderOccurrenceOverrideInput,
+	ReminderOccurrenceOverrideListParams,
+	ReminderPatch,
+	ReminderStorage,
+} from "./types.ts"
+
+import { ReminderSource } from "./reminder-source.ts"
+import {
+	ReminderAction,
+	ReminderEditScope,
+	ReminderPriority,
+	ReminderRecurrenceFrequency,
+	ReminderUpdateResultType,
+	ReminderWeekday,
+} from "./types.ts"
+
+class InMemoryReminderStorage implements ReminderStorage {
+	readonly reminders = new Map<string, Reminder>()
+	readonly overrides = new Map<string, ReminderOccurrenceOverride>()
+	private nextId = 1
+	private readonly listeners = new Set<() => void>()
+
+	constructor(reminders: Reminder[] = []) {
+		for (const reminder of reminders) {
+			this.reminders.set(reminder.id, reminder)
+		}
+	}
+
+	async listReminders(_params: ReminderListParams): Promise<Reminder[]> {
+		return Array.from(this.reminders.values())
+	}
+
+	async getReminder(id: string): Promise<Reminder | null> {
+		return this.reminders.get(id) ?? null
+	}
+
+	async createReminder(input: CreateReminderInput): Promise<Reminder> {
+		const now = new Date("2026-06-01T00:00:00Z")
+		const reminder: Reminder = {
+			id: `reminder-${this.nextId++}`,
+			title: input.title,
+			notes: input.notes ?? null,
+			dueAt: input.dueAt,
+			timeZone: input.timeZone ?? "UTC",
+			recurrence: input.recurrence ?? null,
+			priority: input.priority ?? ReminderPriority.Normal,
+			createdAt: now,
+			updatedAt: now,
+		}
+
+		this.reminders.set(reminder.id, reminder)
+		this.notify()
+		return reminder
+	}
+
+	async updateReminder(id: string, patch: ReminderPatch): Promise<Reminder> {
+		const existing = this.reminders.get(id)
+		if (!existing) {
+			throw new Error(`Reminder not found: ${id}`)
+		}
+
+		const updated: Reminder = {
+			...existing,
+			updatedAt: new Date("2026-06-01T00:01:00Z"),
+		}
+		if (hasOwn(patch, "title")) updated.title = patch.title
+		if (hasOwn(patch, "notes")) updated.notes = patch.notes ?? null
+		if (hasOwn(patch, "dueAt")) updated.dueAt = patch.dueAt
+		if (hasOwn(patch, "timeZone")) updated.timeZone = patch.timeZone
+		if (hasOwn(patch, "recurrence")) updated.recurrence = patch.recurrence ?? null
+		if (hasOwn(patch, "priority")) updated.priority = patch.priority
+
+		this.reminders.set(id, updated)
+		this.notify()
+		return updated
+	}
+
+	async deleteReminder(id: string): Promise<void> {
+		this.reminders.delete(id)
+		this.notify()
+	}
+
+	async listOccurrenceOverrides(
+		params: ReminderOccurrenceOverrideListParams,
+	): Promise<ReminderOccurrenceOverride[]> {
+		const reminderIds = new Set(params.reminderIds)
+		return Array.from(this.overrides.values()).filter(function matches(override) {
+			if (!reminderIds.has(override.reminderId)) return false
+			const dueAt = override.patch?.dueAt ?? override.originalDueAt
+			return (
+				isWithin(override.originalDueAt, params.from, params.to) ||
+				isWithin(dueAt, params.from, params.to)
+			)
+		})
+	}
+
+	async getOccurrenceOverride(
+		reminderId: string,
+		occurrenceId: string,
+	): Promise<ReminderOccurrenceOverride | null> {
+		return this.overrides.get(overrideKey(reminderId, occurrenceId)) ?? null
+	}
+
+	async upsertOccurrenceOverride(
+		input: ReminderOccurrenceOverrideInput,
+	): Promise<ReminderOccurrenceOverride> {
+		const existing = this.overrides.get(overrideKey(input.reminderId, input.occurrenceId))
+		const now = new Date("2026-06-01T00:02:00Z")
+		const override: ReminderOccurrenceOverride = {
+			...existing,
+			...input,
+			createdAt: existing?.createdAt ?? now,
+			updatedAt: now,
+		}
+
+		this.overrides.set(overrideKey(input.reminderId, input.occurrenceId), override)
+		this.notify()
+		return override
+	}
+
+	async deleteOccurrenceOverride(reminderId: string, occurrenceId: string): Promise<void> {
+		this.overrides.delete(overrideKey(reminderId, occurrenceId))
+		this.notify()
+	}
+
+	subscribe(callback: () => void): () => void {
+		this.listeners.add(callback)
+		return () => {
+			this.listeners.delete(callback)
+		}
+	}
+
+	private notify(): void {
+		for (const listener of this.listeners) {
+			listener()
+		}
+	}
+}
+
+function reminder(overrides: Partial<Reminder> = {}): Reminder {
+	const now = new Date("2026-06-01T00:00:00Z")
+	return {
+		id: "r1",
+		title: "Take vitamins",
+		notes: null,
+		dueAt: new Date("2026-06-12T09:00:00Z"),
+		timeZone: "UTC",
+		recurrence: null,
+		priority: ReminderPriority.Normal,
+		createdAt: now,
+		updatedAt: now,
+		...overrides,
+	}
+}
+
+function context(time: string): Context {
+	return new Context(new Date(time))
+}
+
+function overrideKey(reminderId: string, occurrenceId: string): string {
+	return `${reminderId}:${occurrenceId}`
+}
+
+function isWithin(date: Date, from: Date, to: Date): boolean {
+	return date >= from && date <= to
+}
+
+function hasOwn<TObject extends object, TKey extends keyof TObject>(
+	object: TObject,
+	key: TKey,
+): object is TObject & Required<Pick<TObject, TKey>> {
+	return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+describe("ReminderSource", () => {
+	describe("FeedSource interface", () => {
+		test("has correct id and actions", async () => {
+			const source = new ReminderSource({ storage: new InMemoryReminderStorage() })
+
+			expect(source.id).toBe("freya.reminders")
+			const actions = await source.listActions()
+
+			expect(actions[ReminderAction.CreateReminder]?.id).toBe(ReminderAction.CreateReminder)
+			expect(actions[ReminderAction.UpdateReminder]?.id).toBe(ReminderAction.UpdateReminder)
+			expect(actions[ReminderAction.DeleteReminder]?.id).toBe(ReminderAction.DeleteReminder)
+			expect(actions[ReminderAction.CompleteReminder]?.id).toBe(ReminderAction.CompleteReminder)
+			expect(actions[ReminderAction.UncompleteReminder]?.id).toBe(ReminderAction.UncompleteReminder)
+		})
+
+		test("fetchContext returns null", async () => {
+			const source = new ReminderSource({ storage: new InMemoryReminderStorage() })
+
+			await expect(source.fetchContext(context("2026-06-12T09:00:00Z"))).resolves.toBeNull()
+		})
+
+		test("notifies item listeners after source actions", async () => {
+			const storage = new InMemoryReminderStorage()
+			const source = new ReminderSource({ storage })
+			const listener = mock()
+			source.onItemsUpdate(listener)
+
+			await source.createReminder({
+				title: "Buy milk",
+				dueAt: new Date("2026-06-12T18:00:00Z"),
+			})
+
+			expect(listener).toHaveBeenCalled()
+		})
+	})
+
+	describe("fetchItems", () => {
+		test("returns a one-off reminder occurrence", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					id: "buy-milk",
+					title: "Buy milk",
+					dueAt: new Date("2026-06-12T18:00:00Z"),
+				}),
+			])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+
+			const items = await source.fetchItems(context("2026-06-12T12:00:00Z"))
+
+			expect(items).toHaveLength(1)
+			expect(items[0]!.data.title).toBe("Buy milk")
+			expect(items[0]!.data.reminderId).toBe("buy-milk")
+			expect(items[0]!.signals?.timeRelevance).toBe(TimeRelevance.Upcoming)
+		})
+
+		test("expands daily recurrence inside the feed window", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-10T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-12T09:00:00.000Z", "2026-06-13T09:00:00.000Z"])
+		})
+
+		test("expands weekly recurrence on selected weekdays", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday, ReminderWeekday.Wednesday, ReminderWeekday.Friday],
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 6 * 24 * 60 * 60 * 1000,
+			})
+
+			const items = await source.fetchItems(context("2026-06-08T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual([
+				"2026-06-08T09:00:00.000Z",
+				"2026-06-10T09:00:00.000Z",
+				"2026-06-12T09:00:00.000Z",
+			])
+		})
+
+		test("deduplicates weekly weekdays before applying recurrence count", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+						count: 3,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 14 * 24 * 60 * 60 * 1000,
+			})
+
+			const items = await source.fetchItems(context("2026-06-08T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual([
+				"2026-06-08T09:00:00.000Z",
+				"2026-06-10T09:00:00.000Z",
+				"2026-06-15T09:00:00.000Z",
+			])
+		})
+
+		test("omits completed occurrences by default", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.completeReminder({
+				reminderId: "r1",
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				completedAt: new Date("2026-06-12T09:05:00Z"),
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-13T09:00:00.000Z"])
+		})
+	})
+
+	describe("updates", () => {
+		test("updates one recurring occurrence through an override", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const result = await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: {
+					title: "Take vitamins with breakfast",
+					dueAt: new Date("2026-06-12T10:00:00Z"),
+				},
+			})
+
+			expect(result.type).toBe(ReminderUpdateResultType.UpdatedOccurrence)
+			expect(storage.reminders.get("r1")?.title).toBe("Take vitamins")
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(items[0]!.data.title).toBe("Take vitamins with breakfast")
+			expect(items[0]!.data.dueAt.toISOString()).toBe("2026-06-12T10:00:00.000Z")
+			expect(items[1]!.data.title).toBe("Take vitamins")
+		})
+
+		test("updates an entire recurring reminder", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.EntireSeries,
+				patch: { title: "Take medication" },
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(
+				items.map(function title(item) {
+					return item.data.title
+				}),
+			).toEqual(["Take medication", "Take medication"])
+		})
+
+		test("splits a recurring reminder for this-and-future updates", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-10T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const result = await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: {
+					title: "Take vitamins later",
+					dueAt: new Date("2026-06-12T10:00:00Z"),
+				},
+			})
+
+			expect(result.type).toBe(ReminderUpdateResultType.SplitReminder)
+			expect(storage.reminders.size).toBe(2)
+			expect(storage.reminders.get("r1")?.recurrence?.count).toBe(2)
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(
+				items.map(function itemLabel(item) {
+					return `${item.data.title}:${item.data.dueAt.toISOString()}`
+				}),
+			).toEqual([
+				"Take vitamins later:2026-06-12T10:00:00.000Z",
+				"Take vitamins later:2026-06-13T10:00:00.000Z",
+			])
+		})
+
+		test("updates weekly weekdays when a this-and-future split moves weekday", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday],
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 14 * 24 * 60 * 60 * 1000,
+			})
+
+			const result = await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-15T09:00:00Z"),
+				patch: {
+					dueAt: new Date("2026-06-16T09:00:00Z"),
+				},
+			})
+
+			expect(result.type).toBe(ReminderUpdateResultType.SplitReminder)
+			expect(
+				result.type === ReminderUpdateResultType.SplitReminder
+					? result.newReminder.recurrence?.weekdays
+					: null,
+			).toEqual([ReminderWeekday.Tuesday])
+
+			const items = await source.fetchItems(context("2026-06-15T00:00:00Z"))
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-16T09:00:00.000Z", "2026-06-23T09:00:00.000Z"])
+		})
+
+		test("collapses single-occurrence updates on one-off reminders to the reminder", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+
+			await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: { title: "Take supplements" },
+			})
+
+			expect(storage.reminders.get("r1")?.title).toBe("Take supplements")
+			expect(storage.overrides.size).toBe(0)
+		})
+
+		test("rejects one-off scoped updates with a mismatched occurrence", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+			const staleDueAt = new Date("2026-06-13T09:00:00Z")
+
+			for (const scope of [ReminderEditScope.ThisOccurrence, ReminderEditScope.ThisAndFuture]) {
+				await expect(
+					source.updateReminder({
+						reminderId: "r1",
+						scope,
+						occurrenceDueAt: staleDueAt,
+						patch: { title: "Should not apply" },
+					}),
+				).rejects.toThrow("occurrenceDueAt does not match this reminder")
+			}
+
+			expect(storage.reminders.get("r1")?.title).toBe("Take vitamins")
+			expect(storage.overrides.size).toBe(0)
+		})
+	})
+
+	describe("deletes", () => {
+		test("collapses single-occurrence deletes on one-off reminders to the reminder", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+			})
+
+			expect(storage.reminders.has("r1")).toBe(false)
+			expect(storage.overrides.size).toBe(0)
+		})
+
+		test("rejects one-off scoped deletes with a mismatched occurrence", async () => {
+			const storage = new InMemoryReminderStorage([reminder()])
+			const source = new ReminderSource({ storage, lookBackMs: 0 })
+			const staleDueAt = new Date("2026-06-13T09:00:00Z")
+
+			for (const scope of [ReminderEditScope.ThisOccurrence, ReminderEditScope.ThisAndFuture]) {
+				await expect(
+					source.deleteReminder({
+						reminderId: "r1",
+						scope,
+						occurrenceDueAt: staleDueAt,
+					}),
+				).rejects.toThrow("occurrenceDueAt does not match this reminder")
+			}
+
+			expect(storage.reminders.has("r1")).toBe(true)
+			expect(storage.overrides.size).toBe(0)
+		})
+
+		test("deletes one recurring occurrence through an override", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-12T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-13T09:00:00.000Z"])
+		})
+
+		test("deduplicates weekly weekdays before ending this and future", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-08T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Weekly,
+						interval: 1,
+						weekdays: [ReminderWeekday.Monday, ReminderWeekday.Monday, ReminderWeekday.Wednesday],
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 14 * 24 * 60 * 60 * 1000,
+			})
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-10T09:00:00Z"),
+			})
+
+			expect(storage.reminders.get("r1")?.recurrence?.count).toBe(1)
+
+			const items = await source.fetchItems(context("2026-06-08T00:00:00Z"))
+			expect(
+				items.map(function dueAt(item) {
+					return item.data.dueAt.toISOString()
+				}),
+			).toEqual(["2026-06-08T09:00:00.000Z"])
+		})
+
+		test("ignores stale future overrides after deleting this and future", async () => {
+			const storage = new InMemoryReminderStorage([
+				reminder({
+					dueAt: new Date("2026-06-10T09:00:00Z"),
+					recurrence: {
+						frequency: ReminderRecurrenceFrequency.Daily,
+						interval: 1,
+					},
+				}),
+			])
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			await source.updateReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisOccurrence,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+				patch: {
+					title: "Take vitamins later",
+					dueAt: new Date("2026-06-12T10:00:00Z"),
+				},
+			})
+			expect(storage.overrides.size).toBe(1)
+
+			await source.deleteReminder({
+				reminderId: "r1",
+				scope: ReminderEditScope.ThisAndFuture,
+				occurrenceDueAt: new Date("2026-06-12T09:00:00Z"),
+			})
+
+			const items = await source.fetchItems(context("2026-06-12T00:00:00Z"))
+
+			expect(items).toEqual([])
+		})
+	})
+
+	describe("actions", () => {
+		test("executeAction creates reminders from ISO date input", async () => {
+			const storage = new InMemoryReminderStorage()
+			const source = new ReminderSource({
+				storage,
+				lookBackMs: 0,
+				lookAheadMs: 48 * 60 * 60 * 1000,
+			})
+
+			const created = await source.executeAction(ReminderAction.CreateReminder, {
+				title: "Review notes",
+				dueAt: "2026-06-12T15:00:00Z",
+				recurrence: {
+					frequency: "daily",
+					interval: 1,
+					count: 2,
+				},
+			})
+
+			expect((created as Reminder).id).toBe("reminder-1")
+			const items = await source.fetchItems(context("2026-06-12T12:00:00Z"))
+			expect(items).toHaveLength(2)
+		})
+
+		test("executeAction rejects unknown actions", async () => {
+			const source = new ReminderSource({ storage: new InMemoryReminderStorage() })
+
+			await expect(source.executeAction("missing", {})).rejects.toThrow("Unknown action")
+		})
+	})
+})

packages/freya-source-reminders/src/reminder-source.ts

@@ -0,0 +1,633 @@
+import type {
+	ActionDefinition,
+	Context,
+	ContextEntry,
+	FeedItemSignals,
+	FeedSource,
+} from "@freya/core"
+
+import { TimeRelevance, UnknownActionError } from "@freya/core"
+import { type } from "arktype"
+
+import type {
+	CompleteReminderInput,
+	CreateReminderInput,
+	DeleteReminderInput,
+	Reminder,
+	ReminderDeleteResult,
+	ReminderEditScope,
+	ReminderFeedItem,
+	ReminderOccurrence,
+	ReminderOccurrenceOverride,
+	ReminderOccurrenceOverrideInput,
+	ReminderOccurrencePatch,
+	ReminderPatch,
+	ReminderPriority,
+	ReminderStorage,
+	ReminderUpdateResult,
+	UncompleteReminderInput,
+	UpdateReminderInput,
+} from "./types.ts"
+
+import {
+	createReminderOccurrenceId,
+	expandReminderOccurrences,
+	findReminderOccurrenceIndex,
+	recurrenceAfterSplit,
+	stopRecurrenceAfterOccurrenceCount,
+} from "./recurrence.ts"
+import {
+	CompleteReminderInput as CompleteReminderInputSchema,
+	DeleteReminderInput as DeleteReminderInputSchema,
+	ReminderAction,
+	ReminderDeleteResultType,
+	ReminderEditScope as ReminderEditScopeValue,
+	ReminderFeedItemType,
+	ReminderPriority as ReminderPriorityValue,
+	ReminderRecurrenceFrequency,
+	ReminderTimeZoneInput,
+	ReminderUpdateResultType,
+	ReminderWeekday,
+	UncompleteReminderInput as UncompleteReminderInputSchema,
+	UpdateReminderInput as UpdateReminderInputSchema,
+	createReminderInputSchema,
+} from "./types.ts"
+
+interface ArkSchema<T> {
+	(value: unknown): T | InstanceType<typeof type.errors>
+}
+
+export interface ReminderSourceOptions {
+	storage: ReminderStorage
+	/** Default: 24 hours. */
+	lookAheadMs?: number
+	/** Default: 24 hours, so earlier reminders from today remain visible. */
+	lookBackMs?: number
+	/** Default: false. */
+	includeCompleted?: boolean
+	/** Default: UTC. Used when create input omits timeZone. */
+	defaultTimeZone?: string
+}
+
+const DEFAULT_LOOK_AHEAD_MS = 24 * 60 * 60 * 1000
+const DEFAULT_LOOK_BACK_MS = 24 * 60 * 60 * 1000
+const DEFAULT_TIME_ZONE = "UTC"
+
+const FIFTEEN_MINUTES_MS = 15 * 60 * 1000
+const ONE_HOUR_MS = 60 * 60 * 1000
+const ONE_DAY_MS = 24 * 60 * 60 * 1000
+
+/**
+ * FeedSource for one-off and recurring reminders.
+ *
+ * ReminderSource stores only canonical reminders plus occurrence overrides.
+ * It owns recurrence expansion, edit-scope semantics, and feed item signals.
+ */
+export class ReminderSource implements FeedSource<ReminderFeedItem> {
+	readonly id = "freya.reminders"
+
+	private readonly storage: ReminderStorage
+	private readonly lookAheadMs: number
+	private readonly lookBackMs: number
+	private readonly includeCompleted: boolean
+	private readonly defaultTimeZone: string
+	private readonly createReminderInput: ReturnType<typeof createReminderInputSchema>
+	private readonly itemListeners = new Set<(items: ReminderFeedItem[]) => void>()
+
+	constructor(options: ReminderSourceOptions) {
+		this.storage = options.storage
+		this.lookAheadMs = options.lookAheadMs ?? DEFAULT_LOOK_AHEAD_MS
+		this.lookBackMs = options.lookBackMs ?? DEFAULT_LOOK_BACK_MS
+		this.includeCompleted = options.includeCompleted ?? false
+		this.defaultTimeZone = options.defaultTimeZone ?? DEFAULT_TIME_ZONE
+		assertSchema(ReminderTimeZoneInput, this.defaultTimeZone)
+		this.createReminderInput = createReminderInputSchema(this.defaultTimeZone)
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {
+			[ReminderAction.CreateReminder]: {
+				id: ReminderAction.CreateReminder,
+				description: "Create a reminder",
+			},
+			[ReminderAction.UpdateReminder]: {
+				id: ReminderAction.UpdateReminder,
+				description: "Update a reminder or scoped recurrence occurrence",
+			},
+			[ReminderAction.DeleteReminder]: {
+				id: ReminderAction.DeleteReminder,
+				description: "Delete a reminder or scoped recurrence occurrence",
+			},
+			[ReminderAction.CompleteReminder]: {
+				id: ReminderAction.CompleteReminder,
+				description: "Complete a reminder occurrence",
+			},
+			[ReminderAction.UncompleteReminder]: {
+				id: ReminderAction.UncompleteReminder,
+				description: "Clear completion for a reminder occurrence",
+			},
+		}
+	}
+
+	async executeAction(actionId: string, params: unknown): Promise<unknown> {
+		switch (actionId) {
+			case ReminderAction.CreateReminder:
+				return this.createReminder(assertSchema(this.createReminderInput, params))
+			case ReminderAction.UpdateReminder:
+				return this.updateReminder(assertSchema(UpdateReminderInputSchema, params))
+			case ReminderAction.DeleteReminder:
+				return this.deleteReminder(assertSchema(DeleteReminderInputSchema, params))
+			case ReminderAction.CompleteReminder:
+				return this.completeReminder(assertSchema(CompleteReminderInputSchema, params))
+			case ReminderAction.UncompleteReminder:
+				return this.uncompleteReminder(assertSchema(UncompleteReminderInputSchema, params))
+			default:
+				throw new UnknownActionError(actionId)
+		}
+	}
+
+	async fetchContext(_context: Context): Promise<readonly ContextEntry[] | null> {
+		return null
+	}
+
+	onItemsUpdate(callback: (items: ReminderFeedItem[]) => void): () => void {
+		this.itemListeners.add(callback)
+		const cleanupStorage = this.storage.subscribe?.(() => {
+			this.notifyItemsChanged()
+		})
+
+		return () => {
+			this.itemListeners.delete(callback)
+			cleanupStorage?.()
+		}
+	}
+
+	async fetchItems(context: Context): Promise<ReminderFeedItem[]> {
+		const from = new Date(context.time.getTime() - this.lookBackMs)
+		const to = new Date(context.time.getTime() + this.lookAheadMs)
+		const reminders = await this.storage.listReminders({
+			from,
+			to,
+			includeCompleted: this.includeCompleted,
+		})
+
+		if (reminders.length === 0) return []
+
+		const reminderIds = reminders.map(function reminderId(reminder) {
+			return reminder.id
+		})
+		const overrides = await this.storage.listOccurrenceOverrides({ reminderIds, from, to })
+		const overridesByReminderId = groupOverridesByReminderId(overrides)
+
+		const items: ReminderFeedItem[] = []
+		for (const reminder of reminders) {
+			const occurrences = expandReminderOccurrences(reminder, {
+				from,
+				to,
+				includeCompleted: this.includeCompleted,
+				overrides: overridesByReminderId.get(reminder.id),
+			})
+
+			for (const occurrence of occurrences) {
+				items.push(createFeedItem(occurrence, context.time, this.id))
+			}
+		}
+
+		return items.sort(compareFeedItems)
+	}
+
+	async createReminder(input: CreateReminderInput): Promise<Reminder> {
+		const reminder = await this.storage.createReminder(
+			assertSchema(this.createReminderInput, input),
+		)
+		this.notifyItemsChanged()
+		return reminder
+	}
+
+	async updateReminder(input: UpdateReminderInput): Promise<ReminderUpdateResult> {
+		const parsed = assertSchema(UpdateReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const result = await this.updateExistingReminder(reminder, parsed)
+		this.notifyItemsChanged()
+		return result
+	}
+
+	async deleteReminder(input: DeleteReminderInput): Promise<ReminderDeleteResult> {
+		const parsed = assertSchema(DeleteReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const result = await this.deleteExistingReminder(reminder, parsed)
+		this.notifyItemsChanged()
+		return result
+	}
+
+	async completeReminder(input: CompleteReminderInput): Promise<ReminderOccurrenceOverride> {
+		const parsed = assertSchema(CompleteReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const occurrenceDueAt = parsed.occurrenceDueAt
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+			completedAt: parsed.completedAt ?? new Date(),
+			deletedAt: null,
+		})
+
+		this.notifyItemsChanged()
+		return override
+	}
+
+	async uncompleteReminder(input: UncompleteReminderInput): Promise<ReminderOccurrenceOverride> {
+		const parsed = assertSchema(UncompleteReminderInputSchema, input)
+		const reminder = await this.requireReminder(parsed.reminderId)
+		const occurrenceDueAt = parsed.occurrenceDueAt
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+			completedAt: null,
+		})
+
+		this.notifyItemsChanged()
+		return override
+	}
+
+	private async updateExistingReminder(
+		reminder: Reminder,
+		input: UpdateReminderInput,
+	): Promise<ReminderUpdateResult> {
+		if (input.scope === ReminderEditScopeValue.EntireSeries) {
+			const updated = await this.storage.updateReminder(reminder.id, input.patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		const occurrenceDueAt = requireOccurrenceDueAt(input)
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		if (!reminder.recurrence) {
+			const updated = await this.storage.updateReminder(reminder.id, input.patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		if (input.scope === ReminderEditScopeValue.ThisOccurrence) {
+			if (hasOwn(input.patch, "recurrence")) {
+				throw new Error("recurrence cannot be changed for a single occurrence")
+			}
+
+			const { recurrence: _recurrence, ...occurrencePatch } = input.patch
+			const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+				patch: occurrencePatch,
+			})
+			return {
+				type: ReminderUpdateResultType.UpdatedOccurrence,
+				override,
+			}
+		}
+
+		return this.splitReminder(reminder, occurrenceDueAt, input.patch)
+	}
+
+	private async deleteExistingReminder(
+		reminder: Reminder,
+		input: DeleteReminderInput,
+	): Promise<ReminderDeleteResult> {
+		if (input.scope === ReminderEditScopeValue.EntireSeries) {
+			await this.storage.deleteReminder(reminder.id)
+			return { type: ReminderDeleteResultType.DeletedReminder }
+		}
+
+		const occurrenceDueAt = requireOccurrenceDueAt(input)
+		this.requireKnownOccurrence(reminder, occurrenceDueAt)
+
+		if (!reminder.recurrence) {
+			await this.storage.deleteReminder(reminder.id)
+			return { type: ReminderDeleteResultType.DeletedReminder }
+		}
+
+		if (input.scope === ReminderEditScopeValue.ThisOccurrence) {
+			const override = await this.mergeOccurrenceOverride(reminder.id, occurrenceDueAt, {
+				deletedAt: new Date(),
+			})
+			return {
+				type: ReminderDeleteResultType.DeletedOccurrence,
+				override,
+			}
+		}
+
+		const occurrenceIndex = findReminderOccurrenceIndex(reminder, occurrenceDueAt)
+		if (occurrenceIndex === null) {
+			throw new Error("occurrenceDueAt does not match this reminder")
+		}
+		if (occurrenceIndex === 0) {
+			await this.storage.deleteReminder(reminder.id)
+			return { type: ReminderDeleteResultType.DeletedReminder }
+		}
+
+		const recurrence = stopRecurrenceAfterOccurrenceCount(reminder.recurrence, occurrenceIndex)
+		const updated = await this.storage.updateReminder(reminder.id, { recurrence })
+		return {
+			type: ReminderDeleteResultType.EndedReminder,
+			reminder: updated,
+		}
+	}
+
+	private async splitReminder(
+		reminder: Reminder,
+		occurrenceDueAt: Date,
+		patch: ReminderPatch,
+	): Promise<ReminderUpdateResult> {
+		if (!reminder.recurrence) {
+			const updated = await this.storage.updateReminder(reminder.id, patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		const occurrenceIndex = findReminderOccurrenceIndex(reminder, occurrenceDueAt)
+		if (occurrenceIndex === null) {
+			throw new Error("occurrenceDueAt does not match this reminder")
+		}
+
+		if (occurrenceIndex === 0) {
+			const updated = await this.storage.updateReminder(reminder.id, patch)
+			return {
+				type: ReminderUpdateResultType.UpdatedReminder,
+				reminder: updated,
+			}
+		}
+
+		const previousRecurrence = stopRecurrenceAfterOccurrenceCount(
+			reminder.recurrence,
+			occurrenceIndex,
+		)
+		const previousReminder = await this.storage.updateReminder(reminder.id, {
+			recurrence: previousRecurrence,
+		})
+		const newReminder = await this.storage.createReminder(
+			createSplitReminderInput(reminder, occurrenceDueAt, occurrenceIndex, patch),
+		)
+
+		return {
+			type: ReminderUpdateResultType.SplitReminder,
+			previousReminder,
+			newReminder,
+		}
+	}
+
+	private requireKnownOccurrence(reminder: Reminder, occurrenceDueAt: Date): void {
+		const occurrenceIndex = findReminderOccurrenceIndex(reminder, occurrenceDueAt)
+		if (occurrenceIndex === null) {
+			throw new Error("occurrenceDueAt does not match this reminder")
+		}
+	}
+
+	private async requireReminder(id: string): Promise<Reminder> {
+		const reminder = await this.storage.getReminder(id)
+		if (!reminder) {
+			throw new Error(`Reminder not found: ${id}`)
+		}
+		return reminder
+	}
+
+	private async mergeOccurrenceOverride(
+		reminderId: string,
+		originalDueAt: Date,
+		patch: Partial<ReminderOccurrenceOverrideInput>,
+	): Promise<ReminderOccurrenceOverride> {
+		const occurrenceId = createReminderOccurrenceId(originalDueAt)
+		const existing = await this.storage.getOccurrenceOverride(reminderId, occurrenceId)
+
+		const input: ReminderOccurrenceOverrideInput = {
+			reminderId,
+			occurrenceId,
+			originalDueAt,
+			patch: mergeOccurrencePatch(existing?.patch, patch.patch),
+			completedAt: hasOwn(patch, "completedAt")
+				? (patch.completedAt ?? null)
+				: existing?.completedAt,
+			deletedAt: hasOwn(patch, "deletedAt") ? (patch.deletedAt ?? null) : existing?.deletedAt,
+		}
+
+		return this.storage.upsertOccurrenceOverride(input)
+	}
+
+	private notifyItemsChanged(): void {
+		for (const listener of this.itemListeners) {
+			listener([])
+		}
+	}
+}
+
+function createFeedItem(
+	occurrence: ReminderOccurrence,
+	now: Date,
+	sourceId: string,
+): ReminderFeedItem {
+	return {
+		id: `reminder-${occurrence.reminderId}-${occurrence.occurrenceId}`,
+		sourceId,
+		type: ReminderFeedItemType.Reminder,
+		timestamp: now,
+		data: {
+			reminderId: occurrence.reminderId,
+			occurrenceId: occurrence.occurrenceId,
+			title: occurrence.title,
+			notes: occurrence.notes,
+			originalDueAt: occurrence.originalDueAt,
+			dueAt: occurrence.dueAt,
+			timeZone: occurrence.timeZone,
+			recurrence: occurrence.recurrence,
+			priority: occurrence.priority,
+			completedAt: occurrence.completedAt,
+		},
+		signals: computeSignals(occurrence, now),
+	}
+}
+
+function computeSignals(occurrence: ReminderOccurrence, now: Date): FeedItemSignals {
+	if (occurrence.completedAt) {
+		return { urgency: 0, timeRelevance: TimeRelevance.Ambient }
+	}
+
+	const msUntilDue = occurrence.dueAt.getTime() - now.getTime()
+	let urgency: number
+	let timeRelevance: TimeRelevance
+
+	if (msUntilDue < 0) {
+		urgency = 1
+		timeRelevance = TimeRelevance.Imminent
+	} else if (msUntilDue <= FIFTEEN_MINUTES_MS) {
+		urgency = 0.95
+		timeRelevance = TimeRelevance.Imminent
+	} else if (msUntilDue <= ONE_HOUR_MS) {
+		urgency = 0.8
+		timeRelevance = TimeRelevance.Imminent
+	} else if (msUntilDue <= ONE_DAY_MS) {
+		urgency = 0.5
+		timeRelevance = TimeRelevance.Upcoming
+	} else {
+		urgency = 0.2
+		timeRelevance = TimeRelevance.Ambient
+	}
+
+	return {
+		urgency: clamp01(urgency + priorityUrgencyAdjustment(occurrence.priority)),
+		timeRelevance,
+	}
+}
+
+function createSplitReminderInput(
+	reminder: Reminder,
+	occurrenceDueAt: Date,
+	occurrenceIndex: number,
+	patch: ReminderPatch,
+): CreateReminderInput {
+	const dueAt = patch.dueAt ?? occurrenceDueAt
+	const timeZone = patch.timeZone ?? reminder.timeZone
+	const recurrence = hasOwn(patch, "recurrence")
+		? (patch.recurrence ?? null)
+		: alignSplitRecurrence(
+				recurrenceAfterSplit(reminder.recurrence!, occurrenceIndex),
+				occurrenceDueAt,
+				reminder.timeZone,
+				dueAt,
+				timeZone,
+			)
+
+	return {
+		title: patch.title ?? reminder.title,
+		notes: hasOwn(patch, "notes") ? (patch.notes ?? null) : reminder.notes,
+		dueAt,
+		timeZone,
+		recurrence,
+		priority: patch.priority ?? reminder.priority,
+	}
+}
+
+function alignSplitRecurrence(
+	recurrence: Reminder["recurrence"],
+	occurrenceDueAt: Date,
+	occurrenceTimeZone: string,
+	dueAt: Date,
+	timeZone: string,
+): Reminder["recurrence"] {
+	if (
+		!recurrence ||
+		recurrence.frequency !== ReminderRecurrenceFrequency.Weekly ||
+		!recurrence.weekdays?.length
+	) {
+		return recurrence
+	}
+
+	const previousWeekday = weekdayForDate(occurrenceDueAt, occurrenceTimeZone)
+	const nextWeekday = weekdayForDate(dueAt, timeZone)
+	if (previousWeekday === nextWeekday || recurrence.weekdays.includes(nextWeekday)) {
+		return recurrence
+	}
+
+	const weekdays = recurrence.weekdays
+		.filter(function keepOtherWeekdays(weekday) {
+			return weekday !== previousWeekday
+		})
+		.concat(nextWeekday)
+		.sort(compareWeekdays)
+
+	return { ...recurrence, weekdays }
+}
+
+function weekdayForDate(date: Date, timeZone: string): ReminderWeekday {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+	}).formatToParts(date)
+
+	const year = numberDatePart(parts, "year")
+	const month = numberDatePart(parts, "month")
+	const day = numberDatePart(parts, "day")
+	return new Date(Date.UTC(year, month - 1, day)).getUTCDay() as ReminderWeekday
+}
+
+function numberDatePart(
+	parts: Intl.DateTimeFormatPart[],
+	type: Intl.DateTimeFormatPartTypes,
+): number {
+	const part = parts.find(function matchesType(value) {
+		return value.type === type
+	})
+	if (!part) {
+		throw new Error(`Missing ${type} part while formatting reminder date`)
+	}
+	return Number(part.value)
+}
+
+function compareWeekdays(a: ReminderWeekday, b: ReminderWeekday): number {
+	return a - b
+}
+
+function mergeOccurrencePatch(
+	existing: ReminderOccurrencePatch | undefined,
+	next: ReminderOccurrencePatch | undefined,
+): ReminderOccurrencePatch | undefined {
+	if (!existing) return next
+	if (!next) return existing
+	return { ...existing, ...next }
+}
+
+function groupOverridesByReminderId(
+	overrides: readonly ReminderOccurrenceOverride[],
+): Map<string, ReminderOccurrenceOverride[]> {
+	const grouped = new Map<string, ReminderOccurrenceOverride[]>()
+	for (const override of overrides) {
+		const list = grouped.get(override.reminderId) ?? []
+		list.push(override)
+		grouped.set(override.reminderId, list)
+	}
+	return grouped
+}
+
+function priorityUrgencyAdjustment(priority: ReminderPriority): number {
+	switch (priority) {
+		case ReminderPriorityValue.High:
+			return 0.1
+		case ReminderPriorityValue.Low:
+			return -0.1
+		case ReminderPriorityValue.Normal:
+			return 0
+	}
+}
+
+function requireOccurrenceDueAt(input: { scope: ReminderEditScope; occurrenceDueAt?: Date }): Date {
+	if (!input.occurrenceDueAt) {
+		throw new Error(`${input.scope} requires occurrenceDueAt`)
+	}
+	return input.occurrenceDueAt
+}
+
+function assertSchema<T>(schema: ArkSchema<T>, value: unknown): T {
+	const result = schema(value)
+	if (result instanceof type.errors) {
+		throw new Error(result.summary)
+	}
+	return result
+}
+
+function hasOwn<TObject extends object, TKey extends PropertyKey>(
+	object: TObject,
+	key: TKey,
+): object is TObject & Record<TKey, unknown> {
+	return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function clamp01(value: number): number {
+	return Math.max(0, Math.min(1, value))
+}
+
+function compareFeedItems(a: ReminderFeedItem, b: ReminderFeedItem): number {
+	return a.data.dueAt.getTime() - b.data.dueAt.getTime()
+}

packages/freya-source-reminders/src/renderer.tsx

@@ -0,0 +1,62 @@
+/** @jsxImportSource @nym.sh/jrx */
+
+import type { FeedItemRenderer } from "@freya/core"
+
+import { FeedCard, SansSerifText, SerifText } from "@freya/components"
+
+import type { ReminderOccurrenceData } from "./types.ts"
+
+import { ReminderPriority, ReminderRecurrenceFrequency } from "./types.ts"
+
+export const renderReminderFeedItem: FeedItemRenderer<"reminder", ReminderOccurrenceData> = (
+	item,
+) => {
+	const { data } = item
+	const status = data.completedAt ? "Completed" : formatDueStatus(data.dueAt)
+	const recurrence = formatRecurrence(data.recurrence)
+
+	return (
+		<FeedCard>
+			<SansSerifText content={status} style="text-xs uppercase" />
+			<SerifText content={data.title} style="text-lg" />
+			<SansSerifText content={formatDueAt(data.dueAt, data.timeZone)} style="text-sm" />
+			{data.notes ? <SansSerifText content={data.notes} style="text-sm text-secondary" /> : null}
+			{recurrence ? (
+				<SansSerifText content={recurrence} style="text-xs text-secondary uppercase" />
+			) : null}
+			{data.priority !== ReminderPriority.Normal ? (
+				<SansSerifText content={data.priority} style="text-xs text-secondary uppercase" />
+			) : null}
+		</FeedCard>
+	)
+}
+
+function formatDueAt(date: Date, timeZone: string): string {
+	return new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		dateStyle: "medium",
+		timeStyle: "short",
+	}).format(date)
+}
+
+function formatDueStatus(date: Date): string {
+	const now = new Date()
+	if (date.getTime() < now.getTime()) return "Due"
+	return "Upcoming"
+}
+
+function formatRecurrence(recurrence: ReminderOccurrenceData["recurrence"]): string | null {
+	if (!recurrence) return null
+
+	const interval = recurrence.interval === 1 ? "" : `${recurrence.interval} `
+	switch (recurrence.frequency) {
+		case ReminderRecurrenceFrequency.Daily:
+			return recurrence.interval === 1 ? "Daily" : `Every ${interval}days`
+		case ReminderRecurrenceFrequency.Weekly:
+			return recurrence.interval === 1 ? "Weekly" : `Every ${interval}weeks`
+		case ReminderRecurrenceFrequency.Monthly:
+			return recurrence.interval === 1 ? "Monthly" : `Every ${interval}months`
+		case ReminderRecurrenceFrequency.Yearly:
+			return recurrence.interval === 1 ? "Yearly" : `Every ${interval}years`
+	}
+}

packages/freya-source-reminders/src/types.ts

@@ -0,0 +1,373 @@
+import type { FeedItem } from "@freya/core"
+
+import { type } from "arktype"
+
+export const ReminderPriority = {
+	Low: "low",
+	Normal: "normal",
+	High: "high",
+} as const
+
+export type ReminderPriority = (typeof ReminderPriority)[keyof typeof ReminderPriority]
+
+export const ReminderRecurrenceFrequency = {
+	Daily: "daily",
+	Weekly: "weekly",
+	Monthly: "monthly",
+	Yearly: "yearly",
+} as const
+
+export type ReminderRecurrenceFrequency =
+	(typeof ReminderRecurrenceFrequency)[keyof typeof ReminderRecurrenceFrequency]
+
+export const ReminderWeekday = {
+	Sunday: 0,
+	Monday: 1,
+	Tuesday: 2,
+	Wednesday: 3,
+	Thursday: 4,
+	Friday: 5,
+	Saturday: 6,
+} as const
+
+export type ReminderWeekday = (typeof ReminderWeekday)[keyof typeof ReminderWeekday]
+
+export const ReminderEditScope = {
+	ThisOccurrence: "this-occurrence",
+	ThisAndFuture: "this-and-future",
+	EntireSeries: "entire-series",
+} as const
+
+export type ReminderEditScope = (typeof ReminderEditScope)[keyof typeof ReminderEditScope]
+
+export const ReminderAction = {
+	CreateReminder: "create-reminder",
+	UpdateReminder: "update-reminder",
+	DeleteReminder: "delete-reminder",
+	CompleteReminder: "complete-reminder",
+	UncompleteReminder: "uncomplete-reminder",
+} as const
+
+export type ReminderAction = (typeof ReminderAction)[keyof typeof ReminderAction]
+
+export const ReminderUpdateResultType = {
+	UpdatedReminder: "updated-reminder",
+	UpdatedOccurrence: "updated-occurrence",
+	SplitReminder: "split-reminder",
+} as const
+
+export type ReminderUpdateResultType =
+	(typeof ReminderUpdateResultType)[keyof typeof ReminderUpdateResultType]
+
+export const ReminderDeleteResultType = {
+	DeletedReminder: "deleted-reminder",
+	DeletedOccurrence: "deleted-occurrence",
+	EndedReminder: "ended-reminder",
+} as const
+
+export type ReminderDeleteResultType =
+	(typeof ReminderDeleteResultType)[keyof typeof ReminderDeleteResultType]
+
+export const ReminderDateInput = type.or("Date", "string.date.iso.parse")
+export const ReminderTitleInput = type.pipe(
+	type.string,
+	function trimTitle(value) {
+		return value.trim()
+	},
+	type.string.atLeastLength(1),
+)
+export const ReminderTimeZoneInput = type("string", ":", function isTimeZone(value, ctx) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date())
+		return true
+	} catch {
+		return ctx.reject("a valid IANA time zone")
+	}
+})
+
+export const ReminderPriorityInput = type.enumerated(
+	ReminderPriority.Low,
+	ReminderPriority.Normal,
+	ReminderPriority.High,
+)
+
+export const ReminderEditScopeInput = type.enumerated(
+	ReminderEditScope.ThisOccurrence,
+	ReminderEditScope.ThisAndFuture,
+	ReminderEditScope.EntireSeries,
+)
+
+export const ReminderRecurrenceFrequencyInput = type.enumerated(
+	ReminderRecurrenceFrequency.Daily,
+	ReminderRecurrenceFrequency.Weekly,
+	ReminderRecurrenceFrequency.Monthly,
+	ReminderRecurrenceFrequency.Yearly,
+)
+
+export const ReminderWeekdayInput = type.enumerated(0, 1, 2, 3, 4, 5, 6)
+
+export const ReminderRecurrenceInput = type({
+	"+": "reject",
+	frequency: ReminderRecurrenceFrequencyInput,
+	interval: ["number.integer >= 1", "=", 1],
+	"weekdays?": ReminderWeekdayInput.array().atLeastLength(1),
+	"count?": "number.integer >= 1",
+	"until?": ReminderDateInput,
+})
+
+const ReminderRecurrenceNullableInput = type.or(ReminderRecurrenceInput, "null")
+const ReminderNotesInput = type.or("string", "null")
+
+export const ReminderPatchInput = type({
+	"+": "reject",
+	"title?": ReminderTitleInput,
+	"notes?": ReminderNotesInput,
+	"dueAt?": ReminderDateInput,
+	"timeZone?": ReminderTimeZoneInput,
+	"recurrence?": ReminderRecurrenceNullableInput,
+	"priority?": ReminderPriorityInput,
+})
+
+export const ReminderOccurrencePatchInput = type({
+	"+": "reject",
+	"title?": ReminderTitleInput,
+	"notes?": ReminderNotesInput,
+	"dueAt?": ReminderDateInput,
+	"timeZone?": ReminderTimeZoneInput,
+	"priority?": ReminderPriorityInput,
+})
+
+export function createReminderInputSchema(defaultTimeZone: string) {
+	return type({
+		"+": "reject",
+		title: ReminderTitleInput,
+		notes: [ReminderNotesInput, "=", null],
+		dueAt: ReminderDateInput,
+		timeZone: [ReminderTimeZoneInput, "=", defaultTimeZone],
+		recurrence: [ReminderRecurrenceNullableInput, "=", null],
+		priority: [ReminderPriorityInput, "=", ReminderPriority.Normal],
+	})
+}
+
+export const UpdateReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	scope: ReminderEditScopeInput,
+	"occurrenceDueAt?": ReminderDateInput,
+	patch: ReminderPatchInput,
+})
+
+export const DeleteReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	scope: ReminderEditScopeInput,
+	"occurrenceDueAt?": ReminderDateInput,
+})
+
+export const CompleteReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	occurrenceDueAt: ReminderDateInput,
+	"completedAt?": ReminderDateInput,
+})
+
+export const UncompleteReminderInput = type({
+	"+": "reject",
+	reminderId: ReminderTitleInput,
+	occurrenceDueAt: ReminderDateInput,
+})
+
+export interface ReminderRecurrence {
+	frequency: ReminderRecurrenceFrequency
+	/** Repeat every N frequency units. Defaults to 1 when parsed from actions. */
+	interval: number
+	/** Weekly recurrences only. Defaults to the weekday of dueAt. */
+	weekdays?: ReminderWeekday[]
+	/** Maximum number of generated occurrences, including the first one. */
+	count?: number
+	/** Last allowed occurrence instant, inclusive. */
+	until?: Date
+}
+
+export interface Reminder {
+	id: string
+	title: string
+	notes: string | null
+	dueAt: Date
+	timeZone: string
+	recurrence: ReminderRecurrence | null
+	priority: ReminderPriority
+	createdAt: Date
+	updatedAt: Date
+}
+
+export interface CreateReminderInput {
+	title: string
+	notes?: string | null
+	dueAt: Date
+	timeZone?: string
+	recurrence?: ReminderRecurrence | null
+	priority?: ReminderPriority
+}
+
+export interface ReminderPatch {
+	title?: string
+	notes?: string | null
+	dueAt?: Date
+	timeZone?: string
+	recurrence?: ReminderRecurrence | null
+	priority?: ReminderPriority
+}
+
+export interface ReminderOccurrencePatch {
+	title?: string
+	notes?: string | null
+	dueAt?: Date
+	timeZone?: string
+	priority?: ReminderPriority
+}
+
+export interface ReminderOccurrenceOverrideInput {
+	reminderId: string
+	occurrenceId: string
+	originalDueAt: Date
+	patch?: ReminderOccurrencePatch
+	completedAt?: Date | null
+	deletedAt?: Date | null
+}
+
+export interface ReminderOccurrenceOverride extends ReminderOccurrenceOverrideInput {
+	createdAt?: Date
+	updatedAt?: Date
+}
+
+export interface ReminderOccurrence {
+	reminderId: string
+	occurrenceId: string
+	title: string
+	notes: string | null
+	originalDueAt: Date
+	dueAt: Date
+	timeZone: string
+	recurrence: ReminderRecurrence | null
+	priority: ReminderPriority
+	completedAt: Date | null
+}
+
+export interface ReminderListParams {
+	from: Date
+	to: Date
+	includeCompleted: boolean
+}
+
+export interface ReminderOccurrenceOverrideListParams {
+	reminderIds: readonly string[]
+	from: Date
+	to: Date
+}
+
+/**
+ * Storage adapters should return reminders that may produce occurrences in the
+ * requested window. For recurring reminders this can include records whose
+ * first dueAt is before `from`. Returning a superset is valid; ReminderSource
+ * performs final recurrence expansion, override application, and filtering.
+ */
+export interface ReminderStorage {
+	listReminders(params: ReminderListParams): Promise<Reminder[]>
+	getReminder(id: string): Promise<Reminder | null>
+	createReminder(input: CreateReminderInput): Promise<Reminder>
+	updateReminder(id: string, patch: ReminderPatch): Promise<Reminder>
+	deleteReminder(id: string): Promise<void>
+	/**
+	 * Return overrides whose originalDueAt or patched dueAt may affect the
+	 * requested window. Returning a superset is valid.
+	 */
+	listOccurrenceOverrides(
+		params: ReminderOccurrenceOverrideListParams,
+	): Promise<ReminderOccurrenceOverride[]>
+	getOccurrenceOverride(
+		reminderId: string,
+		occurrenceId: string,
+	): Promise<ReminderOccurrenceOverride | null>
+	upsertOccurrenceOverride(
+		input: ReminderOccurrenceOverrideInput,
+	): Promise<ReminderOccurrenceOverride>
+	deleteOccurrenceOverride(reminderId: string, occurrenceId: string): Promise<void>
+	subscribe?(callback: () => void): () => void
+}
+
+export interface UpdateReminderInput {
+	reminderId: string
+	scope: ReminderEditScope
+	occurrenceDueAt?: Date
+	patch: ReminderPatch
+}
+
+export interface DeleteReminderInput {
+	reminderId: string
+	scope: ReminderEditScope
+	occurrenceDueAt?: Date
+}
+
+export interface CompleteReminderInput {
+	reminderId: string
+	occurrenceDueAt: Date
+	completedAt?: Date
+}
+
+export interface UncompleteReminderInput {
+	reminderId: string
+	occurrenceDueAt: Date
+}
+
+export type ReminderUpdateResult =
+	| {
+			type: typeof ReminderUpdateResultType.UpdatedReminder
+			reminder: Reminder
+	  }
+	| {
+			type: typeof ReminderUpdateResultType.UpdatedOccurrence
+			override: ReminderOccurrenceOverride
+	  }
+	| {
+			type: typeof ReminderUpdateResultType.SplitReminder
+			previousReminder: Reminder
+			newReminder: Reminder
+	  }
+
+export type ReminderDeleteResult =
+	| {
+			type: typeof ReminderDeleteResultType.DeletedReminder
+	  }
+	| {
+			type: typeof ReminderDeleteResultType.DeletedOccurrence
+			override: ReminderOccurrenceOverride
+	  }
+	| {
+			type: typeof ReminderDeleteResultType.EndedReminder
+			reminder: Reminder
+	  }
+
+export const ReminderFeedItemType = {
+	Reminder: "reminder",
+} as const
+
+export type ReminderFeedItemType = (typeof ReminderFeedItemType)[keyof typeof ReminderFeedItemType]
+
+export interface ReminderOccurrenceData extends Record<string, unknown> {
+	reminderId: string
+	occurrenceId: string
+	title: string
+	notes: string | null
+	originalDueAt: Date
+	dueAt: Date
+	timeZone: string
+	recurrence: ReminderRecurrence | null
+	priority: ReminderPriority
+	completedAt: Date | null
+}
+
+export type ReminderFeedItem = FeedItem<
+	typeof ReminderFeedItemType.Reminder,
+	ReminderOccurrenceData
+>