feat: add actions to FeedSource interface

Add listActions() and executeAction() to FeedSource for write operations back to external services. Actions use arktype schemas for input validation via StandardSchemaV1. - ActionDefinition type with optional input schema - FeedEngine routes actions with existence and ID validation - Source IDs use reverse-domain format (aris.location, aris.tfl) - LocationSource: update-location action with schema validation - TflSource: set-lines-of-interest action with lineId validation - No-op implementations for sources without actions Co-authored-by: Ona <no-reply@ona.com>
Merge pull request #26 from kennethnym/refactor/required-fetch-context
2026-03-20 09:01:19 +00:00 · 2026-02-15 12:53:10 +00:00 · 2026-02-14 16:41:34 +00:00 · 2026-02-14 16:20:24 +00:00 · 2026-02-14 15:44:03 +00:00 · 2026-02-14 15:43:00 +00:00
50 changed files with 3702 additions and 155 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -32,3 +32,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json

 # Finder (MacOS) folder config
 .DS_Store
+core
--- a/apps/aris-backend/package.json
+++ b/apps/aris-backend/package.json
@@ -11,6 +11,7 @@
 	"dependencies": {
 		"@aris/core": "workspace:*",
 		"@aris/source-location": "workspace:*",
+		"@aris/source-tfl": "workspace:*",
 		"@aris/source-weatherkit": "workspace:*",
 		"@hono/trpc-server": "^0.3",
 		"@trpc/server": "^11",
--- a/apps/aris-backend/src/location/service.test.ts
+++ b/apps/aris-backend/src/location/service.test.ts
@@ -9,7 +9,7 @@ describe("LocationService", () => {
 		const source = service.feedSourceForUser("user-1")

 		expect(source).toBeDefined()
-		expect(source.id).toBe("location")
+		expect(source.id).toBe("aris.location")
 	})

 	test("feedSourceForUser returns same source for same user", () => {
--- a/apps/aris-backend/src/tfl/service.test.ts
+++ b/apps/aris-backend/src/tfl/service.test.ts
@@ -0,0 +1,206 @@
+import type { Context } from "@aris/core"
+import type { ITflApi, StationLocation, TflLineId, TflLineStatus } from "@aris/source-tfl"
+
+import { describe, expect, test } from "bun:test"
+
+import { UserNotFoundError } from "../lib/error.ts"
+import { TflService } from "./service.ts"
+
+class StubTflApi implements ITflApi {
+	private statuses: TflLineStatus[]
+
+	constructor(statuses: TflLineStatus[] = []) {
+		this.statuses = statuses
+	}
+
+	async fetchLineStatuses(lines?: TflLineId[]): Promise<TflLineStatus[]> {
+		if (lines) {
+			return this.statuses.filter((s) => lines.includes(s.lineId))
+		}
+		return this.statuses
+	}
+
+	async fetchStations(): Promise<StationLocation[]> {
+		return [
+			{
+				id: "940GZZLUKSX",
+				name: "King's Cross",
+				lat: 51.5308,
+				lng: -0.1238,
+				lines: ["northern", "victoria"],
+			},
+		]
+	}
+}
+
+function createContext(): Context {
+	return { time: new Date("2026-01-15T12:00:00Z") }
+}
+
+const sampleStatuses: TflLineStatus[] = [
+	{
+		lineId: "northern",
+		lineName: "Northern",
+		severity: "minor-delays",
+		description: "Minor delays on the Northern line",
+	},
+	{
+		lineId: "victoria",
+		lineName: "Victoria",
+		severity: "major-delays",
+		description: "Severe delays on the Victoria line",
+	},
+	{
+		lineId: "central",
+		lineName: "Central",
+		severity: "closure",
+		description: "Central line suspended",
+	},
+]
+
+describe("TflService", () => {
+	test("feedSourceForUser creates source on first call", () => {
+		const service = new TflService(new StubTflApi())
+		const source = service.feedSourceForUser("user-1")
+
+		expect(source).toBeDefined()
+		expect(source.id).toBe("aris.tfl")
+	})
+
+	test("feedSourceForUser returns same source for same user", () => {
+		const service = new TflService(new StubTflApi())
+		const source1 = service.feedSourceForUser("user-1")
+		const source2 = service.feedSourceForUser("user-1")
+
+		expect(source1).toBe(source2)
+	})
+
+	test("feedSourceForUser returns different sources for different users", () => {
+		const service = new TflService(new StubTflApi())
+		const source1 = service.feedSourceForUser("user-1")
+		const source2 = service.feedSourceForUser("user-2")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("updateLinesOfInterest mutates the existing source in place", () => {
+		const service = new TflService(new StubTflApi())
+		const original = service.feedSourceForUser("user-1")
+
+		service.updateLinesOfInterest("user-1", ["northern", "victoria"])
+		const after = service.feedSourceForUser("user-1")
+
+		expect(after).toBe(original)
+	})
+
+	test("updateLinesOfInterest throws if source does not exist", () => {
+		const service = new TflService(new StubTflApi())
+
+		expect(() => service.updateLinesOfInterest("user-1", ["northern"])).toThrow(UserNotFoundError)
+	})
+
+	test("removeUser removes the source", () => {
+		const service = new TflService(new StubTflApi())
+		const source1 = service.feedSourceForUser("user-1")
+
+		service.removeUser("user-1")
+		const source2 = service.feedSourceForUser("user-1")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("removeUser clears line configuration", async () => {
+		const api = new StubTflApi(sampleStatuses)
+		const service = new TflService(api)
+		service.feedSourceForUser("user-1")
+		service.updateLinesOfInterest("user-1", ["northern"])
+
+		service.removeUser("user-1")
+		const items = await service.feedSourceForUser("user-1").fetchItems(createContext())
+
+		expect(items.length).toBe(3)
+	})
+
+	test("shares single api instance across users", () => {
+		const api = new StubTflApi()
+		const service = new TflService(api)
+
+		service.feedSourceForUser("user-1")
+		service.feedSourceForUser("user-2")
+
+		expect(service.feedSourceForUser("user-1").id).toBe("aris.tfl")
+		expect(service.feedSourceForUser("user-2").id).toBe("aris.tfl")
+	})
+
+	describe("returned source fetches items", () => {
+		test("source returns feed items from api", async () => {
+			const api = new StubTflApi(sampleStatuses)
+			const service = new TflService(api)
+			const source = service.feedSourceForUser("user-1")
+
+			const items = await source.fetchItems(createContext())
+
+			expect(items.length).toBe(3)
+			for (const item of items) {
+				expect(item.type).toBe("tfl-alert")
+				expect(item.id).toMatch(/^tfl-alert-/)
+				expect(typeof item.priority).toBe("number")
+				expect(item.timestamp).toBeInstanceOf(Date)
+			}
+		})
+
+		test("source returns items sorted by priority descending", async () => {
+			const api = new StubTflApi(sampleStatuses)
+			const service = new TflService(api)
+			const source = service.feedSourceForUser("user-1")
+
+			const items = await source.fetchItems(createContext())
+
+			for (let i = 1; i < items.length; i++) {
+				expect(items[i - 1]!.priority).toBeGreaterThanOrEqual(items[i]!.priority)
+			}
+		})
+
+		test("source returns empty array when no disruptions", async () => {
+			const api = new StubTflApi([])
+			const service = new TflService(api)
+			const source = service.feedSourceForUser("user-1")
+
+			const items = await source.fetchItems(createContext())
+
+			expect(items).toEqual([])
+		})
+
+		test("updateLinesOfInterest filters items to configured lines", async () => {
+			const api = new StubTflApi(sampleStatuses)
+			const service = new TflService(api)
+
+			const before = await service.feedSourceForUser("user-1").fetchItems(createContext())
+			expect(before.length).toBe(3)
+
+			service.updateLinesOfInterest("user-1", ["northern"])
+			const after = await service.feedSourceForUser("user-1").fetchItems(createContext())
+
+			expect(after.length).toBe(1)
+			expect(after[0]!.data.line).toBe("northern")
+		})
+
+		test("different users get independent line configs", async () => {
+			const api = new StubTflApi(sampleStatuses)
+			const service = new TflService(api)
+			service.feedSourceForUser("user-1")
+			service.feedSourceForUser("user-2")
+
+			service.updateLinesOfInterest("user-1", ["northern"])
+			service.updateLinesOfInterest("user-2", ["central"])
+
+			const items1 = await service.feedSourceForUser("user-1").fetchItems(createContext())
+			const items2 = await service.feedSourceForUser("user-2").fetchItems(createContext())
+
+			expect(items1.length).toBe(1)
+			expect(items1[0]!.data.line).toBe("northern")
+			expect(items2.length).toBe(1)
+			expect(items2[0]!.data.line).toBe("central")
+		})
+	})
+})
--- a/apps/aris-backend/src/tfl/service.ts
+++ b/apps/aris-backend/src/tfl/service.ts
@@ -0,0 +1,40 @@
+import { TflSource, type ITflApi, type TflLineId } from "@aris/source-tfl"
+
+import type { FeedSourceProvider } from "../feed/service.ts"
+
+import { UserNotFoundError } from "../lib/error.ts"
+
+/**
+ * Manages per-user TflSource instances with individual line configuration.
+ */
+export class TflService implements FeedSourceProvider {
+	private sources = new Map<string, TflSource>()
+
+	constructor(private readonly api: ITflApi) {}
+
+	feedSourceForUser(userId: string): TflSource {
+		let source = this.sources.get(userId)
+		if (!source) {
+			source = new TflSource({ client: this.api })
+			this.sources.set(userId, source)
+		}
+		return source
+	}
+
+	/**
+	 * Update monitored lines for a user. Mutates the existing TflSource
+	 * so that references held by FeedEngine remain valid.
+	 * @throws {UserNotFoundError} If no source exists for the user
+	 */
+	updateLinesOfInterest(userId: string, lines: TflLineId[]): void {
+		const source = this.sources.get(userId)
+		if (!source) {
+			throw new UserNotFoundError(userId)
+		}
+		source.setLinesOfInterest(lines)
+	}
+
+	removeUser(userId: string): void {
+		this.sources.delete(userId)
+	}
+}
--- a/apps/aris-backend/src/weather/service.test.ts
+++ b/apps/aris-backend/src/weather/service.test.ts
@@ -34,7 +34,7 @@ describe("WeatherService", () => {
 		const source = service.feedSourceForUser("user-1")

 		expect(source).toBeDefined()
-		expect(source.id).toBe("weather")
+		expect(source.id).toBe("aris.weather")
 	})

 	test("feedSourceForUser returns same source for same user", () => {
--- a/bun.lock
+++ b/bun.lock
@@ -19,6 +19,7 @@
      "dependencies": {
        "@aris/core": "workspace:*",
        "@aris/source-location": "workspace:*",
+        "@aris/source-tfl": "workspace:*",
        "@aris/source-weatherkit": "workspace:*",
        "@hono/trpc-server": "^0.3",
        "@trpc/server": "^11",
@@ -34,6 +35,9 @@
    "packages/aris-core": {
      "name": "@aris/core",
      "version": "0.0.0",
+      "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
+      },
    },
    "packages/aris-data-source-weatherkit": {
      "name": "@aris/data-source-weatherkit",
@@ -43,11 +47,29 @@
        "arktype": "^2.1.0",
      },
    },
+    "packages/aris-source-apple-calendar": {
+      "name": "@aris/source-apple-calendar",
+      "version": "0.0.0",
+      "dependencies": {
+        "@aris/core": "workspace:*",
+        "ical.js": "^2.1.0",
+        "tsdav": "^2.1.7",
+      },
+    },
+    "packages/aris-source-google-calendar": {
+      "name": "@aris/source-google-calendar",
+      "version": "0.0.0",
+      "dependencies": {
+        "@aris/core": "workspace:*",
+        "arktype": "^2.1.0",
+      },
+    },
    "packages/aris-source-location": {
      "name": "@aris/source-location",
      "version": "0.0.0",
      "dependencies": {
        "@aris/core": "workspace:*",
+        "arktype": "^2.1.0",
      },
    },
    "packages/aris-source-tfl": {
@@ -76,6 +98,10 @@

    "@aris/data-source-weatherkit": ["@aris/data-source-weatherkit@workspace:packages/aris-data-source-weatherkit"],

+    "@aris/source-apple-calendar": ["@aris/source-apple-calendar@workspace:packages/aris-source-apple-calendar"],
+
+    "@aris/source-google-calendar": ["@aris/source-google-calendar@workspace:packages/aris-source-google-calendar"],
+
    "@aris/source-location": ["@aris/source-location@workspace:packages/aris-source-location"],

    "@aris/source-tfl": ["@aris/source-tfl@workspace:packages/aris-source-tfl"],
@@ -86,9 +112,9 @@

    "@ark/util": ["@ark/util@0.56.0", "", {}, "sha512-BghfRC8b9pNs3vBoDJhcta0/c1J1rsoS1+HgVUreMFPdhz/CRAKReAu57YEllNaSy98rWAdY1gE+gFup7OXpgA=="],

-    "@better-auth/core": ["@better-auth/core@1.4.17", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "zod": "^4.3.5" }, "peerDependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "better-call": "1.1.8", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" } }, "sha512-WSaEQDdUO6B1CzAmissN6j0lx9fM9lcslEYzlApB5UzFaBeAOHNUONTdglSyUs6/idiZBoRvt0t/qMXCgIU8ug=="],
+    "@better-auth/core": ["@better-auth/core@1.4.18", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "zod": "^4.3.5" }, "peerDependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "better-call": "1.1.8", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" } }, "sha512-q+awYgC7nkLEBdx2sW0iJjkzgSHlIxGnOpsN1r/O1+a4m7osJNHtfK2mKJSL1I+GfNyIlxJF8WvD/NLuYMpmcg=="],

-    "@better-auth/telemetry": ["@better-auth/telemetry@1.4.17", "", { "dependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21" }, "peerDependencies": { "@better-auth/core": "1.4.17" } }, "sha512-R1BC4e/bNjQbXu7lG6ubpgmsPj7IMqky5DvMlzAtnAJWJhh99pMh/n6w5gOHa0cqDZgEAuj75IPTxv+q3YiInA=="],
+    "@better-auth/telemetry": ["@better-auth/telemetry@1.4.18", "", { "dependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21" }, "peerDependencies": { "@better-auth/core": "1.4.18" } }, "sha512-e5rDF8S4j3Um/0LIVATL2in9dL4lfO2fr2v1Wio4qTMRbfxqnUDTa+6SZtwdeJrbc4O+a3c+IyIpjG9Q/6GpfQ=="],

    "@better-auth/utils": ["@better-auth/utils@0.3.0", "", {}, "sha512-W+Adw6ZA6mgvnSnhOki270rwJ42t4XzSK6YWGF//BbVXL6SwCLWfyzBc1lN2m/4RM28KubdBKQ4X5VMoLRNPQw=="],

@@ -116,29 +142,51 @@

    "@oxfmt/win32-x64": ["@oxfmt/win32-x64@0.24.0", "", { "os": "win32", "cpu": "x64" }, "sha512-0tmlNzcyewAnauNeBCq0xmAkmiKzl+H09p0IdHy+QKrTQdtixtf+AOjDAADbRfihkS+heF15Pjc4IyJMdAAJjw=="],

-    "@oxlint/darwin-arm64": ["@oxlint/darwin-arm64@1.39.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-lT3hNhIa02xCujI6YGgjmYGg3Ht/X9ag5ipUVETaMpx5Rd4BbTNWUPif1WN1YZHxt3KLCIqaAe7zVhatv83HOQ=="],
+    "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.47.0", "", { "os": "android", "cpu": "arm" }, "sha512-UHqo3te9K/fh29brCuQdHjN+kfpIi9cnTPABuD5S9wb9ykXYRGTOOMVuSV/CK43sOhU4wwb2nT1RVjcbrrQjFw=="],

-    "@oxlint/darwin-x64": ["@oxlint/darwin-x64@1.39.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-UT+rfTWd+Yr7iJeSLd/7nF8X4gTYssKh+n77hxl6Oilp3NnG1CKRHxZDy3o3lIBnwgzJkdyUAiYWO1bTMXQ1lA=="],
+    "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.47.0", "", { "os": "android", "cpu": "arm64" }, "sha512-xh02lsTF1TAkR+SZrRMYHR/xCx8Wg2MAHxJNdHVpAKELh9/yE9h4LJeqAOBbIb3YYn8o/D97U9VmkvkfJfrHfw=="],

-    "@oxlint/linux-arm64-gnu": ["@oxlint/linux-arm64-gnu@1.39.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-qocBkvS2V6rH0t9AT3DfQunMnj3xkM7srs5/Ycj2j5ZqMoaWd/FxHNVJDFP++35roKSvsRJoS0mtA8/77jqm6Q=="],
+    "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.47.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-OSOfNJqabOYbkyQDGT5pdoL+05qgyrmlQrvtCO58M4iKGEQ/xf3XkkKj7ws+hO+k8Y4VF4zGlBsJlwqy7qBcHA=="],

-    "@oxlint/linux-arm64-musl": ["@oxlint/linux-arm64-musl@1.39.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-arZzAc1PPcz9epvGBBCMHICeyQloKtHX3eoOe62B3Dskn7gf6Q14wnDHr1r9Vp4vtcBATNq6HlKV14smdlC/qA=="],
+    "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.47.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-hP2bOI4IWNS+F6pVXWtRshSTuJ1qCRZgDgVUg6EBUqsRy+ExkEPJkx+YmIuxgdCduYK1LKptLNFuQLJP8voPbQ=="],

-    "@oxlint/linux-x64-gnu": ["@oxlint/linux-x64-gnu@1.39.0", "", { "os": "linux", "cpu": "x64" }, "sha512-ZVt5qsECpuNprdWxAPpDBwoixr1VTcZ4qAEQA2l/wmFyVPDYFD3oBY/SWACNnWBddMrswjTg9O8ALxYWoEpmXw=="],
+    "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.47.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-F55jIEH5xmGu7S661Uho8vGiLFk0bY3A/g4J8CTKiLJnYu/PSMZ2WxFoy5Hji6qvFuujrrM9Q8XXbMO0fKOYPg=="],

-    "@oxlint/linux-x64-musl": ["@oxlint/linux-x64-musl@1.39.0", "", { "os": "linux", "cpu": "x64" }, "sha512-pB0hlGyKPbxr9NMIV783lD6cWL3MpaqnZRM9MWni4yBdHPTKyFNYdg5hGD0Bwg+UP4S2rOevq/+OO9x9Bi7E6g=="],
+    "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.47.0", "", { "os": "linux", "cpu": "arm" }, "sha512-wxmOn/wns/WKPXUC1fo5mu9pMZPVOu8hsynaVDrgmmXMdHKS7on6bA5cPauFFN9tJXNdsjW26AK9lpfu3IfHBQ=="],

-    "@oxlint/win32-arm64": ["@oxlint/win32-arm64@1.39.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gg2SFaJohI9+tIQVKXlPw3FsPQFi/eCSWiCgwPtPn5uzQxHRTeQEZKuluz1fuzR5U70TXubb2liZi4Dgl8LJQA=="],
+    "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.47.0", "", { "os": "linux", "cpu": "arm" }, "sha512-KJTmVIA/GqRlM2K+ZROH30VMdydEU7bDTY35fNg3tOPzQRIs2deLZlY/9JWwdWo1F/9mIYmpbdCmPqtKhWNOPg=="],

-    "@oxlint/win32-x64": ["@oxlint/win32-x64@1.39.0", "", { "os": "win32", "cpu": "x64" }, "sha512-sbi25lfj74hH+6qQtb7s1wEvd1j8OQbTaH8v3xTcDjrwm579Cyh0HBv1YSZ2+gsnVwfVDiCTL1D0JsNqYXszVA=="],
+    "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.47.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-PF7ELcFg1GVlS0X0ZB6aWiXobjLrAKer3T8YEkwIoO8RwWiAMkL3n3gbleg895BuZkHVlJ2kPRUwfrhHrVkD1A=="],
+
+    "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.47.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-4BezLRO5cu0asf0Jp1gkrnn2OHiXrPPPEfBTxq1k5/yJ2zdGGTmZxHD2KF2voR23wb8Elyu3iQawXo7wvIZq0Q=="],
+
+    "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.47.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-aI5ds9jq2CPDOvjeapiIj48T/vlWp+f4prkxs+FVzrmVN9BWIj0eqeJ/hV8WgXg79HVMIz9PU6deI2ki09bR1w=="],
+
+    "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.47.0", "", { "os": "linux", "cpu": "none" }, "sha512-mO7ycp9Elvgt5EdGkQHCwJA6878xvo9tk+vlMfT1qg++UjvOMB8INsOCQIOH2IKErF/8/P21LULkdIrocMw9xA=="],
+
+    "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.47.0", "", { "os": "linux", "cpu": "none" }, "sha512-24D0wsYT/7hDFn3Ow32m3/+QT/1ZwrUhShx4/wRDAmz11GQHOZ1k+/HBuK/MflebdnalmXWITcPEy4BWTi7TCA=="],
+
+    "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.47.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-8tPzPne882mtML/uy3mApvdCyuVOpthJ7xUv3b67gVfz63hOOM/bwO0cysSkPyYYFDFRn6/FnUb7Jhmsesntvg=="],
+
+    "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.47.0", "", { "os": "linux", "cpu": "x64" }, "sha512-q58pIyGIzeffEBhEgbRxLFHmHfV9m7g1RnkLiahQuEvyjKNiJcvdHOwKH2BdgZxdzc99Cs6hF5xTa86X40WzPw=="],
+
+    "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.47.0", "", { "os": "linux", "cpu": "x64" }, "sha512-e7DiLZtETZUCwTa4EEHg9G+7g3pY+afCWXvSeMG7m0TQ29UHHxMARPaEQUE4mfKgSqIWnJaUk2iZzRPMRdga5g=="],
+
+    "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.47.0", "", { "os": "none", "cpu": "arm64" }, "sha512-3AFPfQ0WKMleT/bKd7zsks3xoawtZA6E/wKf0DjwysH7wUiMMJkNKXOzYq1R/00G98JFgSU1AkrlOQrSdNNhlg=="],
+
+    "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.47.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-cLMVVM6TBxp+N7FldQJ2GQnkcLYEPGgiuEaXdvhgvSgODBk9ov3jed+khIXSAWtnFOW0wOnG3RjwqPh0rCuheA=="],
+
+    "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.47.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-VpFOSzvTnld77/Edje3ZdHgZWnlTb5nVWXyTgjD3/DKF/6t5bRRbwn3z77zOdnGy44xAMvbyAwDNOSeOdVUmRA=="],
+
+    "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.47.0", "", { "os": "win32", "cpu": "x64" }, "sha512-+q8IWptxXx2HMTM6JluR67284t0h8X/oHJgqpxH1siowxPMqZeIpAcWCUq+tY+Rv2iQK8TUugjZnSBQAVV5CmA=="],

    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],

-    "@trpc/server": ["@trpc/server@11.8.1", "", { "peerDependencies": { "typescript": ">=5.7.2" } }, "sha512-P4rzZRpEL7zDFgjxK65IdyH0e41FMFfTkQkuq0BA5tKcr7E6v9/v38DEklCpoDN6sPiB1Sigy/PUEzHENhswDA=="],
+    "@trpc/server": ["@trpc/server@11.10.0", "", { "peerDependencies": { "typescript": ">=5.7.2" } }, "sha512-zZjTrR6He61e5TiT7e/bQqab/jRcXBZM8Fg78Yoo8uh5pz60dzzbYuONNUCOkafv5ppXVMms4NHYfNZgzw50vg=="],

-    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],

-    "@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
+    "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],

    "@types/pg": ["@types/pg@8.16.0", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-RmhMd/wD+CF8Dfo+cVIy3RR5cl8CyfXQ0tGgW6XBL8L4LM/UTEbNXYRbLwU6w+CgrKBNbrQWt4FUtTfaU5jSYQ=="],

@@ -146,31 +194,43 @@

    "arktype": ["arktype@2.1.29", "", { "dependencies": { "@ark/schema": "0.56.0", "@ark/util": "0.56.0", "arkregex": "0.0.5" } }, "sha512-jyfKk4xIOzvYNayqnD8ZJQqOwcrTOUbIU4293yrzAjA3O1dWh61j71ArMQ6tS/u4pD7vabSPe7nG3RCyoXW6RQ=="],

-    "better-auth": ["better-auth@1.4.17", "", { "dependencies": { "@better-auth/core": "1.4.17", "@better-auth/telemetry": "1.4.17", "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "@noble/ciphers": "^2.0.0", "@noble/hashes": "^2.0.0", "better-call": "1.1.8", "defu": "^6.1.4", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1", "zod": "^4.3.5" }, "peerDependencies": { "@lynx-js/react": "*", "@prisma/client": "^5.0.0 || ^6.0.0 || ^7.0.0", "@sveltejs/kit": "^2.0.0", "@tanstack/react-start": "^1.0.0", "@tanstack/solid-start": "^1.0.0", "better-sqlite3": "^12.0.0", "drizzle-kit": ">=0.31.4", "drizzle-orm": ">=0.41.0", "mongodb": "^6.0.0 || ^7.0.0", "mysql2": "^3.0.0", "next": "^14.0.0 || ^15.0.0 || ^16.0.0", "pg": "^8.0.0", "prisma": "^5.0.0 || ^6.0.0 || ^7.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0", "solid-js": "^1.0.0", "svelte": "^4.0.0 || ^5.0.0", "vitest": "^2.0.0 || ^3.0.0 || ^4.0.0", "vue": "^3.0.0" }, "optionalPeers": ["@lynx-js/react", "@prisma/client", "@sveltejs/kit", "@tanstack/react-start", "@tanstack/solid-start", "better-sqlite3", "drizzle-kit", "drizzle-orm", "mongodb", "mysql2", "next", "pg", "prisma", "react", "react-dom", "solid-js", "svelte", "vitest", "vue"] }, "sha512-VmHGQyKsEahkEs37qguROKg/6ypYpNF13D7v/lkbO7w7Aivz0Bv2h+VyUkH4NzrGY0QBKXi1577mGhDCVwp0ew=="],
+    "base-64": ["base-64@1.0.0", "", {}, "sha512-kwDPIFCGx0NZHog36dj+tHiwP4QMzsZ3AgMViUBKI0+V5n4U0ufTCUMhnQ04diaRI8EX/QcPfql7zlhZ7j4zgg=="],
+
+    "better-auth": ["better-auth@1.4.18", "", { "dependencies": { "@better-auth/core": "1.4.18", "@better-auth/telemetry": "1.4.18", "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "@noble/ciphers": "^2.0.0", "@noble/hashes": "^2.0.0", "better-call": "1.1.8", "defu": "^6.1.4", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1", "zod": "^4.3.5" }, "peerDependencies": { "@lynx-js/react": "*", "@prisma/client": "^5.0.0 || ^6.0.0 || ^7.0.0", "@sveltejs/kit": "^2.0.0", "@tanstack/react-start": "^1.0.0", "@tanstack/solid-start": "^1.0.0", "better-sqlite3": "^12.0.0", "drizzle-kit": ">=0.31.4", "drizzle-orm": ">=0.41.0", "mongodb": "^6.0.0 || ^7.0.0", "mysql2": "^3.0.0", "next": "^14.0.0 || ^15.0.0 || ^16.0.0", "pg": "^8.0.0", "prisma": "^5.0.0 || ^6.0.0 || ^7.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0", "solid-js": "^1.0.0", "svelte": "^4.0.0 || ^5.0.0", "vitest": "^2.0.0 || ^3.0.0 || ^4.0.0", "vue": "^3.0.0" }, "optionalPeers": ["@lynx-js/react", "@prisma/client", "@sveltejs/kit", "@tanstack/react-start", "@tanstack/solid-start", "better-sqlite3", "drizzle-kit", "drizzle-orm", "mongodb", "mysql2", "next", "pg", "prisma", "react", "react-dom", "solid-js", "svelte", "vitest", "vue"] }, "sha512-bnyifLWBPcYVltH3RhS7CM62MoelEqC6Q+GnZwfiDWNfepXoQZBjEvn4urcERC7NTKgKq5zNBM8rvPvRBa6xcg=="],

    "better-call": ["better-call@1.1.8", "", { "dependencies": { "@better-auth/utils": "^0.3.0", "@better-fetch/fetch": "^1.1.4", "rou3": "^0.7.10", "set-cookie-parser": "^2.7.1" }, "peerDependencies": { "zod": "^4.0.0" }, "optionalPeers": ["zod"] }, "sha512-XMQ2rs6FNXasGNfMjzbyroSwKwYbZ/T3IxruSS6U2MJRsSYh3wYtG3o6H00ZlKZ/C/UPOAD97tqgQJNsxyeTXw=="],

-    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "cross-fetch": ["cross-fetch@4.1.0", "", { "dependencies": { "node-fetch": "^2.7.0" } }, "sha512-uKm5PU+MHTootlWEY+mZ4vvXoCn4fLQxT9dSc1sXVMSFkINTJVN8cAQROpwcKm8bJ/c7rgZVIBWzH5T78sNZZw=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],

    "defu": ["defu@6.1.4", "", {}, "sha512-mEQCMmwJu317oSz8CwdIOdwf3xMif1ttiM8LTufzc3g6kR+9Pe236twL8j3IYT1F7GfRgGcW6MWxzZjLIkuHIg=="],

-    "hono": ["hono@4.11.5", "", {}, "sha512-WemPi9/WfyMwZs+ZUXdiwcCh9Y+m7L+8vki9MzDw3jJ+W9Lc+12HGsd368Qc1vZi1xwW8BWMMsnK5efYKPdt4g=="],
+    "hono": ["hono@4.11.9", "", {}, "sha512-Eaw2YTGM6WOxA6CXbckaEvslr2Ne4NFsKrvc0v97JD5awbmeBLO5w9Ho9L9kmKonrwF9RJlW6BxT1PVv/agBHQ=="],
+
+    "ical.js": ["ical.js@2.2.1", "", {}, "sha512-yK/UlPbEs316igb/tjRgbFA8ZV75rCsBJp/hWOatpyaPNlgw0dGDmU+FoicOcwX4xXkeXOkYiOmCqNPFpNPkQg=="],

    "jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],

-    "kysely": ["kysely@0.28.10", "", {}, "sha512-ksNxfzIW77OcZ+QWSAPC7yDqUSaIVwkTWnTPNiIy//vifNbwsSgQ57OkkncHxxpcBHM3LRfLAZVEh7kjq5twVA=="],
+    "kysely": ["kysely@0.28.11", "", {}, "sha512-zpGIFg0HuoC893rIjYX1BETkVWdDnzTzF5e0kWXJFg5lE0k1/LfNWBejrcnOFu8Q2Rfq/hTDTU7XLUM8QOrpzg=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],

    "nanostores": ["nanostores@1.1.0", "", {}, "sha512-yJBmDJr18xy47dbNVlHcgdPrulSn1nhSE6Ns9vTG+Nx9VPT6iV1MD6aQFp/t52zpf82FhLLTXAXr30NuCnxvwA=="],

+    "node-fetch": ["node-fetch@2.7.0", "", { "dependencies": { "whatwg-url": "^5.0.0" }, "peerDependencies": { "encoding": "^0.1.0" }, "optionalPeers": ["encoding"] }, "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A=="],
+
    "oxfmt": ["oxfmt@0.24.0", "", { "dependencies": { "tinypool": "2.0.0" }, "optionalDependencies": { "@oxfmt/darwin-arm64": "0.24.0", "@oxfmt/darwin-x64": "0.24.0", "@oxfmt/linux-arm64-gnu": "0.24.0", "@oxfmt/linux-arm64-musl": "0.24.0", "@oxfmt/linux-x64-gnu": "0.24.0", "@oxfmt/linux-x64-musl": "0.24.0", "@oxfmt/win32-arm64": "0.24.0", "@oxfmt/win32-x64": "0.24.0" }, "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-UjeM3Peez8Tl7IJ9s5UwAoZSiDRMww7BEc21gDYxLq3S3/KqJnM3mjNxsoSHgmBvSeX6RBhoVc2MfC/+96RdSw=="],

-    "oxlint": ["oxlint@1.39.0", "", { "optionalDependencies": { "@oxlint/darwin-arm64": "1.39.0", "@oxlint/darwin-x64": "1.39.0", "@oxlint/linux-arm64-gnu": "1.39.0", "@oxlint/linux-arm64-musl": "1.39.0", "@oxlint/linux-x64-gnu": "1.39.0", "@oxlint/linux-x64-musl": "1.39.0", "@oxlint/win32-arm64": "1.39.0", "@oxlint/win32-x64": "1.39.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.10.0" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-wSiLr0wjG+KTU6c1LpVoQk7JZ7l8HCKlAkVDVTJKWmCGazsNxexxnOXl7dsar92mQcRnzko5g077ggP3RINSjA=="],
+    "oxlint": ["oxlint@1.47.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.47.0", "@oxlint/binding-android-arm64": "1.47.0", "@oxlint/binding-darwin-arm64": "1.47.0", "@oxlint/binding-darwin-x64": "1.47.0", "@oxlint/binding-freebsd-x64": "1.47.0", "@oxlint/binding-linux-arm-gnueabihf": "1.47.0", "@oxlint/binding-linux-arm-musleabihf": "1.47.0", "@oxlint/binding-linux-arm64-gnu": "1.47.0", "@oxlint/binding-linux-arm64-musl": "1.47.0", "@oxlint/binding-linux-ppc64-gnu": "1.47.0", "@oxlint/binding-linux-riscv64-gnu": "1.47.0", "@oxlint/binding-linux-riscv64-musl": "1.47.0", "@oxlint/binding-linux-s390x-gnu": "1.47.0", "@oxlint/binding-linux-x64-gnu": "1.47.0", "@oxlint/binding-linux-x64-musl": "1.47.0", "@oxlint/binding-openharmony-arm64": "1.47.0", "@oxlint/binding-win32-arm64-msvc": "1.47.0", "@oxlint/binding-win32-ia32-msvc": "1.47.0", "@oxlint/binding-win32-x64-msvc": "1.47.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.11.2" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-v7xkK1iv1qdvTxJGclM97QzN8hHs5816AneFAQ0NGji1BMUquhiDAhXpMwp8+ls16uRVJtzVHxP9pAAXblDeGA=="],

-    "pg": ["pg@8.17.2", "", { "dependencies": { "pg-connection-string": "^2.10.1", "pg-pool": "^3.11.0", "pg-protocol": "^1.11.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.3.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-vjbKdiBJRqzcYw1fNU5KuHyYvdJ1qpcQg1CeBrHFqV1pWgHeVR6j/+kX0E1AAXfyuLUGY1ICrN2ELKA/z2HWzw=="],
+    "pg": ["pg@8.18.0", "", { "dependencies": { "pg-connection-string": "^2.11.0", "pg-pool": "^3.11.0", "pg-protocol": "^1.11.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.3.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-xqrUDL1b9MbkydY/s+VZ6v+xiMUmOUk7SS9d/1kpyQxoJ6U9AO1oIJyUWVZojbfe5Cc/oluutcgFG4L9RDP1iQ=="],

    "pg-cloudflare": ["pg-cloudflare@1.3.0", "", {}, "sha512-6lswVVSztmHiRtD6I8hw4qP/nDm1EJbKMRhf3HCYaqud7frGysPv7FYJ5noZQdhQtN2xJnimfMtvQq21pdbzyQ=="],

-    "pg-connection-string": ["pg-connection-string@2.10.1", "", {}, "sha512-iNzslsoeSH2/gmDDKiyMqF64DATUCWj3YJ0wP14kqcsf2TUklwimd+66yYojKwZCA7h2yRNLGug71hCBA2a4sw=="],
+    "pg-connection-string": ["pg-connection-string@2.11.0", "", {}, "sha512-kecgoJwhOpxYU21rZjULrmrBJ698U2RxXofKVzOn5UDj61BPj/qMb7diYUR1nLScCDbrztQFl1TaQZT0t1EtzQ=="],

    "pg-int8": ["pg-int8@1.0.1", "", {}, "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw=="],

@@ -192,16 +252,28 @@

    "rou3": ["rou3@0.7.12", "", {}, "sha512-iFE4hLDuloSWcD7mjdCDhx2bKcIsYbtOTpfH5MHHLSKMOUyjqQXTeZVa289uuwEGEKFoE/BAPbhaU4B774nceg=="],

+    "sax": ["sax@1.4.4", "", {}, "sha512-1n3r/tGXO6b6VXMdFT54SHzT9ytu9yr7TaELowdYpMqY/Ao7EnlQGmAQ1+RatX7Tkkdm6hONI2owqNx2aZj5Sw=="],
+
    "set-cookie-parser": ["set-cookie-parser@2.7.2", "", {}, "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw=="],

    "split2": ["split2@4.2.0", "", {}, "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg=="],

    "tinypool": ["tinypool@2.0.0", "", {}, "sha512-/RX9RzeH2xU5ADE7n2Ykvmi9ED3FBGPAjw9u3zucrNNaEBIO0HPSYgL0NT7+3p147ojeSdaVu08F6hjpv31HJg=="],

+    "tr46": ["tr46@0.0.3", "", {}, "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="],
+
+    "tsdav": ["tsdav@2.1.8", "", { "dependencies": { "base-64": "1.0.0", "cross-fetch": "4.1.0", "debug": "4.4.3", "xml-js": "1.6.11" } }, "sha512-zvQvhZLzTaEmNNgJbBlUYT/JOq9Xpw/xkxCqs7IT2d2/7o7pss0iZOlZXuHJ5VcvSvTny42Vc6+6GyzZcrCJ1g=="],
+
    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],

    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],

+    "webidl-conversions": ["webidl-conversions@3.0.1", "", {}, "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="],
+
+    "whatwg-url": ["whatwg-url@5.0.0", "", { "dependencies": { "tr46": "~0.0.3", "webidl-conversions": "^3.0.0" } }, "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw=="],
+
+    "xml-js": ["xml-js@1.6.11", "", { "dependencies": { "sax": "^1.2.4" }, "bin": { "xml-js": "./bin/cli.js" } }, "sha512-7rVi2KMfwfWFl+GpPg6m80IVMWXLRjO+PxTq7V2CDhoGak0wzYzFgUY2m4XJ47OGdXd8eLE8EmwfAmdjw7lC1g=="],
+
    "xtend": ["xtend@4.0.2", "", {}, "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ=="],

    "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
--- a/docs/backend-service-architecture-spec.md
+++ b/docs/backend-service-architecture-spec.md
@@ -0,0 +1,306 @@
+# Backend Service Architecture: Per-User Refactor
+
+## Problem Statement
+
+The current backend uses a **per-source service** pattern: each source type (Location, Weather, TFL) has its own `XxxService` class that manages a `Map<userId, SourceInstance>`. Adding a new source requires:
+
+1. A new `XxxService` class with identical boilerplate (~30-40 lines: Map, get-or-create, removeUser)
+2. Wiring it into `server.ts` constructor
+3. Passing it to `FeedEngineService`
+4. Optionally adding source-specific tRPC routes
+
+With 3 sources this is manageable. With 10+ (calendar, music, transit, news, etc.) it becomes:
+
+- **Repetitive**: Every service class repeats the same Map + get-or-create + removeUser pattern
+- **Fragmented lifecycle**: User cleanup requires calling `removeUser` on every service independently
+- **No user-level config**: No unified place to store which sources a user has enabled or their per-source settings
+- **Hard to reason about**: User state is scattered across N independent Maps
+
+### Current Flow
+
+```
+server.ts
+  ├── new LocationService()          ← owns Map<userId, LocationSource>
+  ├── new WeatherService(creds)      ← owns Map<userId, WeatherSource>
+  ├── new TflService(api)            ← owns Map<userId, TflSource>
+  └── FeedEngineService([loc, weather, tfl])
+        └── owns Map<userId, FeedEngine>
+            └── on create: asks each service for feedSourceForUser(userId)
+```
+
+4 independent Maps for 3 sources. Each user's state lives in 4 different places.
+
+## Scope
+
+**Backend only** (`apps/aris-backend`). No changes to `aris-core` or source packages (`packages/aris-source-*`). The `FeedSource` interface and source implementations remain unchanged.
+
+## Architectural Options
+
+### Option A: UserSession Object
+
+A single `UserSession` class owns everything for one user. A `UserSessionManager` is the only top-level Map.
+
+```typescript
+class UserSession {
+  readonly userId: string
+  readonly engine: FeedEngine
+  private sources: Map<string, FeedSource>
+
+  constructor(userId: string, sourceFactories: SourceFactory[]) {
+    this.engine = new FeedEngine()
+    this.sources = new Map()
+    for (const factory of sourceFactories) {
+      const source = factory.create()
+      this.sources.set(source.id, source)
+      this.engine.register(source)
+    }
+    this.engine.start()
+  }
+
+  getSource<T extends FeedSource>(id: string): T | undefined {
+    return this.sources.get(id) as T | undefined
+  }
+
+  destroy(): void {
+    this.engine.stop()
+    this.sources.clear()
+  }
+}
+
+class UserSessionManager {
+  private sessions = new Map<string, UserSession>()
+
+  getOrCreate(userId: string): UserSession { ... }
+  remove(userId: string): void { ... }  // single cleanup point
+}
+```
+
+**Source-specific operations** use typed accessors:
+
+```typescript
+const session = manager.getOrCreate(userId)
+const location = session.getSource<LocationSource>("location")
+location?.pushLocation({ lat: 51.5, lng: -0.1, ... })
+```
+
+**Pros:**
+
+- Single Map, single cleanup point
+- All user state co-located
+- Easy to add TTL/eviction at one level
+- Source factories are simple functions, no service classes needed
+
+**Cons:**
+
+- `getSource<T>("id")` requires callers to know the source ID string and cast type
+- Shared resources (e.g., TFL API client) need to be passed through factories
+
+### Option B: Source Registry with Factories
+
+Keep `FeedEngineService` but replace per-source service classes with a registry of factory functions. No `XxxService` classes at all.
+
+```typescript
+interface SourceFactory {
+  readonly sourceId: string
+  create(userId: string): FeedSource
+}
+
+// Weather factory — closure over shared credentials
+function weatherSourceFactory(creds: WeatherKitCredentials): SourceFactory {
+  return {
+    sourceId: "weather",
+    create: () => new WeatherSource({ credentials: creds }),
+  }
+}
+
+// TFL factory — closure over shared API client
+function tflSourceFactory(api: ITflApi): SourceFactory {
+  return {
+    sourceId: "tfl",
+    create: () => new TflSource({ client: api }),
+  }
+}
+
+class FeedEngineService {
+  private engines = new Map<string, FeedEngine>()
+  private userSources = new Map<string, Map<string, FeedSource>>()
+
+  constructor(private readonly factories: SourceFactory[]) {}
+
+  engineForUser(userId: string): FeedEngine { ... }
+  getSourceForUser<T extends FeedSource>(userId: string, sourceId: string): T | undefined { ... }
+  removeUser(userId: string): void { ... }  // cleans up engine + all sources
+}
+```
+
+**Pros:**
+
+- Minimal change from current structure — `FeedEngineService` evolves, services disappear
+- Factory functions are 5-10 lines each, no classes
+- Shared resources handled naturally via closures
+
+**Cons:**
+
+- `FeedEngineService` grows in responsibility (engine + source tracking + source access)
+- Still two Maps (engines + userSources), though co-located
+
+### Option C: UserSession + Typed Source Handles (Recommended)
+
+Combines Option A's co-location with type-safe source access. `UserSession` owns everything. Source-specific operations go through **source handles** — thin typed wrappers registered at setup time.
+
+```typescript
+// Source handle: typed wrapper for source-specific operations
+interface SourceHandle<T extends FeedSource = FeedSource> {
+	readonly source: T
+}
+
+class UserSession {
+	readonly engine: FeedEngine
+	private handles = new Map<string, SourceHandle>()
+
+	register<T extends FeedSource>(source: T): SourceHandle<T> {
+		this.engine.register(source)
+		const handle: SourceHandle<T> = { source }
+		this.handles.set(source.id, handle)
+		return handle
+	}
+
+	destroy(): void {
+		this.engine.stop()
+		this.handles.clear()
+	}
+}
+
+// In setup code — handles are typed at creation time
+function createSession(userId: string, deps: SessionDeps): UserSession {
+	const session = new UserSession(userId)
+
+	const locationHandle = session.register(new LocationSource())
+	const weatherHandle = session.register(new WeatherSource(deps.weatherCreds))
+	const tflHandle = session.register(new TflSource({ client: deps.tflApi }))
+
+	return session
+}
+```
+
+**Source-specific operations** use the typed handles returned at registration:
+
+```typescript
+// In the tRPC router or wherever source-specific ops happen:
+// The handle is obtained during session setup and stored where needed
+locationHandle.source.pushLocation({ ... })
+tflHandle.source.setLinesOfInterest(["northern"])
+```
+
+**Pros:**
+
+- Single Map, single cleanup
+- Type-safe source access without string-based lookups or casts
+- No boilerplate service classes
+- Handles can be extended later (e.g., add per-source config, metrics)
+- Shared resources passed directly to constructors
+
+**Cons:**
+
+- Handles need to be threaded to where they're used (tRPC routers, etc.)
+- Slightly more setup code in the factory function
+
+## Source-Specific Operations: Approaches
+
+Orthogonal to the session model, there are three ways to handle operations like `pushLocation` or `setLinesOfInterest`:
+
+### Approach 1: Direct Source Access (Recommended)
+
+Callers get a typed reference to the source and call methods directly. This is what all three options above use in different ways.
+
+```typescript
+locationSource.pushLocation(location)
+tflSource.setLinesOfInterest(lines)
+```
+
+**Why this works:** Source packages already define these methods. The backend just needs to expose the source instance to the right caller. No new abstraction needed.
+
+### Approach 2: Command Dispatch
+
+A generic `dispatch(command)` method on the session routes typed commands to sources.
+
+```typescript
+session.dispatch({ type: "location.update", payload: { lat: 51.5, ... } })
+```
+
+**Tradeoff:** Adds indirection and a command type registry. Useful if sources are dynamically loaded plugins, but over-engineered for the current case where sources are known at compile time.
+
+### Approach 3: Context-Only
+
+All input goes through `FeedEngine` context updates. Sources react to context changes.
+
+```typescript
+engine.pushContext({ [LocationKey]: location })
+// LocationSource picks this up via onContextUpdate
+```
+
+**Tradeoff:** Location already works this way (it's a context provider). But not all operations map to context — `setLinesOfInterest` is configuration, not context. Would require stretching the context concept.
+
+## User Source Configuration (DB-Persisted)
+
+Regardless of which option is chosen, user source config needs a storage model:
+
+```sql
+CREATE TABLE user_source_config (
+  user_id    TEXT NOT NULL REFERENCES users(id),
+  source_id  TEXT NOT NULL,          -- e.g., "weather", "tfl", "location"
+  enabled    BOOLEAN NOT NULL DEFAULT true,
+  config     JSONB NOT NULL DEFAULT '{}',  -- source-specific settings
+  PRIMARY KEY (user_id, source_id)
+);
+```
+
+On session creation:
+
+1. Load `user_source_config` rows for the user
+2. Only create sources where `enabled = true`
+3. Pass `config` JSON to the source factory/constructor
+
+New users get default config rows inserted on first login.
+
+## Recommendation
+
+**Option C (UserSession + Typed Source Handles)** with **Approach 1 (Direct Source Access)**.
+
+Rationale:
+
+- Eliminates all per-source service boilerplate
+- Single user lifecycle management point
+- Type-safe without string-based lookups in hot paths
+- Minimal new abstraction — `UserSession` is a thin container, not a framework
+- Handles are just typed references, not a new pattern to learn
+- Natural extension point for per-user config loading from DB
+
+## Acceptance Criteria
+
+1. **No per-source service classes**: `LocationService`, `WeatherService`, `TflService` are removed
+2. **Single user state container**: All per-user state (engine, sources) lives in one object
+3. **Single cleanup**: Removing a user requires one call, not N
+4. **Type-safe source access**: Source-specific operations don't require string-based lookups or unsafe casts at call sites
+5. **Existing tests pass**: `FeedEngineService` tests are migrated to the new structure
+6. **tRPC routes work**: Location update route works through the new architecture
+7. **DB config table**: `user_source_config` table exists; session creation reads from it
+8. **Default config**: New users get default source config on first session
+
+## Implementation Steps
+
+1. Create `user_source_config` DB table and migration
+2. Create `UserSession` class with `register()`, `destroy()`, typed handle return
+3. Create `UserSessionManager` with `getOrCreate()`, `remove()`, config loading
+4. Create `createSession()` factory that reads DB config and registers enabled sources
+5. Refactor `server.ts` to use `UserSessionManager` instead of individual services
+6. Refactor tRPC router to receive session/handles instead of individual services
+7. Delete `LocationService`, `WeatherService`, `TflService` classes
+8. Migrate existing tests to new structure
+9. Add tests for session lifecycle (create, destroy, config loading)
+
+## Open Questions
+
+- **TTL/eviction**: Should `UserSessionManager` handle idle session cleanup? (Currently deferred in backend-spec.md)
+- **Hot reload config**: If a user changes their source config, should the session be recreated or patched in-place?
+- **Shared source instances**: Some sources (e.g., TFL) share an API client. Should the factory receive shared deps, or should there be a DI container?
--- a/docs/feed-source-actions-spec.md
+++ b/docs/feed-source-actions-spec.md
@@ -0,0 +1,269 @@
+# FeedSource Actions
+
+## Problem Statement
+
+`FeedSource` is read-only. Sources can provide context and feed items but can't expose write operations (play, RSVP, dismiss). This blocks interactive sources like Spotify, calendar, and tasks.
+
+## Scope
+
+**`aris-core` only.** Add action support to `FeedSource` and `FeedItem`. No changes to existing fields or methods — purely additive.
+
+## Design
+
+### Why Not MCP
+
+MCP was considered. It doesn't fit because:
+
+- MCP resources don't accept input context (FeedSource needs accumulated context as input)
+- MCP has no structured feed items (priority, timestamp, type)
+- MCP's isolation model conflicts with ARIS's dependency graph
+- Adding these as MCP extensions would mean the extensions are the entire protocol
+
+The interface is designed to be **protocol-compatible** — a future `RemoteFeedSource` adapter can map each field/method to a JSON-RPC operation without changing the interface:
+
+| FeedSource field/method | Future protocol operation |
+| ----------------------- | ------------------------- |
+| `id`, `dependencies`    | `source/describe`         |
+| `listActions()`         | `source/listActions`      |
+| `fetchContext()`        | `source/fetchContext`     |
+| `fetchItems()`          | `source/fetchItems`       |
+| `executeAction()`       | `source/executeAction`    |
+| `onContextUpdate()`     | `source/contextUpdated`   |
+| `onItemsUpdate()`       | `source/itemsUpdated`     |
+
+No interface changes needed when the transport layer is built.
+
+### Source ID & Action ID Convention
+
+Source IDs use reverse domain notation. Built-in sources use `aris.<name>`. Third parties use their own domain.
+
+Action IDs are descriptive verb-noun pairs in kebab-case, scoped to their source. The globally unique form is `<sourceId>/<actionId>`.
+
+| Source ID       | Action IDs                                                     |
+| --------------- | -------------------------------------------------------------- |
+| `aris.location` | `update-location` (migrated from `pushLocation()`)             |
+| `aris.tfl`      | `set-lines-of-interest` (migrated from `setLinesOfInterest()`) |
+| `aris.weather`  | _(none)_                                                       |
+| `com.spotify`   | `play-track`, `pause-playback`, `skip-track`, `like-track`     |
+| `aris.calendar` | `rsvp`, `create-event`                                         |
+| `com.todoist`   | `complete-task`, `snooze-task`                                 |
+
+This means existing source packages need their `id` updated (e.g., `"location"` → `"aris.location"`).
+
+### New Types
+
+```typescript
+/** Describes an action a source can perform. */
+interface ActionDefinition<TInput = unknown> {
+	/** Descriptive action name in kebab-case (e.g., "update-location", "play-track") */
+	readonly id: string
+	/** Human-readable label for UI (e.g., "Play", "RSVP Yes") */
+	readonly label: string
+	/** Optional longer description */
+	readonly description?: string
+	/** Schema for input validation. Accepts any Standard Schema compatible validator (arktype, zod, valibot, etc.). Omit if no params. */
+	readonly input?: StandardSchemaV1<TInput>
+}
+```
+
+`StandardSchemaV1` is the [Standard Schema](https://github.com/standard-schema/standard-schema) interface implemented by arktype, zod, and valibot. This means sources can use any validator:
+
+```typescript
+import { type } from "arktype"
+import { z } from "zod"
+
+// With arktype
+{ id: "play-track", label: "Play", input: type({ trackId: "string" }) }
+
+// With zod
+{ id: "play-track", label: "Play", input: z.object({ trackId: z.string() }) }
+
+// Without validation (e.g., remote sources using raw JSON Schema)
+{ id: "play-track", label: "Play" }
+
+/** Result of executing an action. */
+interface ActionResult {
+  ok: boolean
+  data?: Record<string, unknown>
+  error?: string
+}
+
+/** Reference to an action on a specific feed item. */
+interface ItemAction {
+  /** Action ID (matches ActionDefinition.id on the source) */
+  actionId: string
+  /** Per-item label override (e.g., "RSVP to standup") */
+  label?: string
+  /** Pre-filled params for this item (e.g., { eventId: "abc" }) */
+  params?: Record<string, unknown>
+}
+```
+
+### Changes to FeedSource
+
+Two optional fields added. Nothing else changes.
+
+```typescript
+interface FeedSource<TItem extends FeedItem = FeedItem> {
+  readonly id: string                              // unchanged
+  readonly dependencies?: readonly string[]        // unchanged
+  fetchContext(...): ...                            // unchanged
+  onContextUpdate?(...): ...                       // unchanged
+  fetchItems?(...): ...                            // unchanged
+  onItemsUpdate?(...): ...                         // unchanged
+
+  /** List actions this source supports. Empty record if none. Maps to: source/listActions */
+  listActions(): Promise<Record<string, ActionDefinition>>
+
+  /** Execute an action by ID. No-op returning { ok: false } if source has no actions. */
+  executeAction(
+    actionId: string,
+    params: Record<string, unknown>,
+  ): Promise<ActionResult>
+}
+```
+
+### Changes to FeedItem
+
+One optional field added.
+
+```typescript
+interface FeedItem<
+	TType extends string = string,
+	TData extends Record<string, unknown> = Record<string, unknown>,
+> {
+	id: string // unchanged
+	type: TType // unchanged
+	priority: number // unchanged
+	timestamp: Date // unchanged
+	data: TData // unchanged
+
+	/** Actions the user can take on this item. */
+	actions?: readonly ItemAction[]
+}
+```
+
+### Changes to FeedEngine
+
+Two new methods. Existing methods unchanged.
+
+```typescript
+class FeedEngine {
+	// All existing methods unchanged...
+
+	/** Route an action call to the correct source. */
+	async executeAction(
+		sourceId: string,
+		actionId: string,
+		params: Record<string, unknown>,
+	): Promise<ActionResult>
+
+	/** List all actions across all registered sources. */
+	listActions(): { sourceId: string; actions: readonly ActionDefinition[] }[]
+}
+```
+
+### Example: Spotify Source
+
+```typescript
+class SpotifySource implements FeedSource<SpotifyFeedItem> {
+	readonly id = "com.spotify"
+
+	async listActions() {
+		return {
+			"play-track": { id: "play-track", label: "Play", input: type({ trackId: "string" }) },
+			"pause-playback": { id: "pause-playback", label: "Pause" },
+			"skip-track": { id: "skip-track", label: "Skip" },
+			"like-track": { id: "like-track", label: "Like", input: type({ trackId: "string" }) },
+		}
+	}
+
+	async executeAction(actionId: string, params: Record<string, unknown>): Promise<ActionResult> {
+		switch (actionId) {
+			case "play-track":
+				await this.client.play(params.trackId as string)
+				return { ok: true }
+			case "pause-playback":
+				await this.client.pause()
+				return { ok: true }
+			case "skip-track":
+				await this.client.skip()
+				return { ok: true }
+			case "like-track":
+				await this.client.like(params.trackId as string)
+				return { ok: true }
+			default:
+				return { ok: false, error: `Unknown action: ${actionId}` }
+		}
+	}
+
+	async fetchContext(): Promise<null> {
+		return null
+	}
+
+	// Note: for a source with no actions, it would be:
+	// async listActions() { return {} }
+	// async executeAction(): Promise<ActionResult> {
+	//   return { ok: false, error: "No actions supported" }
+	// }
+
+	async fetchItems(context: Context): Promise<SpotifyFeedItem[]> {
+		const track = await this.client.getCurrentTrack()
+		if (!track) return []
+		return [
+			{
+				id: `spotify-${track.id}`,
+				type: "spotify-now-playing",
+				priority: 0.4,
+				timestamp: context.time,
+				data: { trackName: track.name, artist: track.artist },
+				actions: [
+					{ actionId: "pause-playback" },
+					{ actionId: "skip-track" },
+					{ actionId: "like-track", params: { trackId: track.id } },
+				],
+			},
+		]
+	}
+}
+```
+
+## Acceptance Criteria
+
+1. `ActionDefinition` type exists with `id`, `label`, `description?`, `inputSchema?`
+2. `ActionResult` type exists with `ok`, `data?`, `error?`
+3. `ItemAction` type exists with `actionId`, `label?`, `params?`
+4. `FeedSource.listActions()` is a required method returning `Record<string, ActionDefinition>` (empty record if no actions)
+5. `FeedSource.executeAction()` is a required method (no-op for sources without actions)
+6. `FeedItem.actions` is an optional readonly array of `ItemAction`
+7. `FeedEngine.executeAction()` routes to correct source, returns `ActionResult`
+8. `FeedEngine.listActions()` aggregates actions from all sources
+9. Existing tests pass unchanged (all changes are additive)
+10. New tests: action execution, unknown action ID, unknown source ID, source without actions, `listActions()` aggregation
+
+## Implementation Steps
+
+1. Create `action.ts` in `aris-core/src` with `ActionDefinition`, `ActionResult`, `ItemAction`
+2. Add optional `actions` and `executeAction` to `FeedSource` interface in `feed-source.ts`
+3. Add optional `actions` field to `FeedItem` interface in `feed.ts`
+4. Add `executeAction()` and `listActions()` to `FeedEngine` in `feed-engine.ts`
+5. Export new types from `aris-core/index.ts`
+6. Add tests for `FeedEngine.executeAction()` routing
+7. Add tests for `FeedEngine.listActions()` aggregation
+8. Add tests for error cases (unknown action, unknown source, source without actions)
+9. Update source IDs to reverse-domain format (`"location"` → `"aris.location"`, etc.) across all source packages
+10. Migrate `LocationSource.pushLocation()` → action `update-location` on `aris.location`
+11. Migrate `TflSource.setLinesOfInterest()` → action `set-lines-of-interest` on `aris.tfl`
+12. Add `async listActions() { return {} }` and no-op `executeAction()` to sources without actions (WeatherSource, GoogleCalendarSource, AppleCalendarSource)
+13. Update any tests or code referencing old source IDs
+14. Run all tests to confirm nothing breaks
+
+## What This Defers
+
+- Transport layer (JSON-RPC over HTTP/WebSocket) — built when remote sources are needed
+- `RemoteFeedSource` adapter — mechanical once transport exists
+- MCP adapter — wraps MCP servers as FeedSource
+- Runtime schema validation of action params
+- Action permissions / confirmation UI
+- Source discovery / registry API
+- Backend service consolidation (separate spec, depends on this one)
--- a/packages/aris-core/package.json
+++ b/packages/aris-core/package.json
@@ -6,5 +6,8 @@
 	"types": "src/index.ts",
 	"scripts": {
 		"test": "bun test ."
+	},
+	"dependencies": {
+		"@standard-schema/spec": "^1.1.0"
 	}
 }
--- a/packages/aris-core/src/action.ts
+++ b/packages/aris-core/src/action.ts
@@ -0,0 +1,27 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+
+/**
+ * Describes an action a source can perform.
+ *
+ * Action IDs use descriptive verb-noun kebab-case (e.g., "update-location", "play-track").
+ * Combined with the source's reverse-domain ID, they form a globally unique identifier:
+ * `<sourceId>/<actionId>` (e.g., "aris.location/update-location").
+ */
+export class UnknownActionError extends Error {
+	readonly actionId: string
+
+	constructor(actionId: string) {
+		super(`Unknown action: ${actionId}`)
+		this.name = "UnknownActionError"
+		this.actionId = actionId
+	}
+}
+
+export interface ActionDefinition<TInput = unknown> {
+	/** Descriptive action name in kebab-case (e.g., "update-location", "play-track") */
+	readonly id: string
+	/** Optional longer description */
+	readonly description?: string
+	/** Schema for input validation. Accepts any Standard Schema compatible validator (arktype, zod, valibot, etc.). */
+	readonly input?: StandardSchemaV1<TInput>
+}
--- a/packages/aris-core/src/feed-engine.test.ts
+++ b/packages/aris-core/src/feed-engine.test.ts
@@ -1,9 +1,19 @@
 import { describe, expect, test } from "bun:test"

-import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
+import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"

 import { FeedEngine } from "./feed-engine"
-import { contextKey, contextValue } from "./index"
+import { UnknownActionError, contextKey, contextValue } from "./index"
+
+// No-op action methods for test sources
+const noActions = {
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	},
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	},
+}

 // =============================================================================
 // CONTEXT KEYS
@@ -43,6 +53,7 @@ function createLocationSource(): SimulatedLocationSource {

 	return {
 		id: "location",
+		...noActions,

 		onContextUpdate(cb) {
 			callback = cb
@@ -71,10 +82,11 @@ function createWeatherSource(
 	return {
 		id: "weather",
 		dependencies: ["location"],
+		...noActions,

 		async fetchContext(context) {
 			const location = contextValue(context, LocationKey)
-			if (!location) return {}
+			if (!location) return null

 			const weather = await fetchWeather(location)
 			return { [WeatherKey]: weather }
@@ -104,6 +116,11 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 	return {
 		id: "alert",
 		dependencies: ["weather"],
+		...noActions,
+
+		async fetchContext() {
+			return null
+		},

 		async fetchItems(context) {
 			const weather = contextValue(context, WeatherKey)
@@ -164,39 +181,78 @@ describe("FeedEngine", () => {
 	})

 	describe("graph validation", () => {
-		test("throws on missing dependency", () => {
+		test("throws on missing dependency", async () => {
 			const engine = new FeedEngine()
 			const orphan: FeedSource = {
 				id: "orphan",
 				dependencies: ["nonexistent"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 			}

 			engine.register(orphan)

-			expect(engine.refresh()).rejects.toThrow(
+			await expect(engine.refresh()).rejects.toThrow(
 				'Source "orphan" depends on "nonexistent" which is not registered',
 			)
 		})

-		test("throws on circular dependency", () => {
+		test("throws on circular dependency", async () => {
 			const engine = new FeedEngine()
-			const a: FeedSource = { id: "a", dependencies: ["b"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}

 			engine.register(a).register(b)

-			expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
+			await expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
 		})

-		test("throws on longer cycles", () => {
+		test("throws on longer cycles", async () => {
 			const engine = new FeedEngine()
-			const a: FeedSource = { id: "a", dependencies: ["c"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
-			const c: FeedSource = { id: "c", dependencies: ["b"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["c"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const c: FeedSource = {
+				id: "c",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}

 			engine.register(a).register(b).register(c)

-			expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
+			await expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
 		})
 	})

@@ -206,6 +262,7 @@ describe("FeedEngine", () => {

 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					order.push("location")
 					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -215,6 +272,7 @@ describe("FeedEngine", () => {
 			const weather: FeedSource = {
 				id: "weather",
 				dependencies: ["location"],
+				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
 					const loc = contextValue(ctx, LocationKey)
@@ -240,8 +298,14 @@ describe("FeedEngine", () => {

 			const { context } = await engine.refresh()

-			expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
-			expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
+			expect(contextValue(context, LocationKey)).toEqual({
+				lat: 51.5,
+				lng: -0.1,
+			})
+			expect(contextValue(context, WeatherKey)).toEqual({
+				temperature: 20,
+				condition: "sunny",
+			})
 		})

 		test("collects items from all sources", async () => {
@@ -281,8 +345,9 @@ describe("FeedEngine", () => {
 		test("handles missing upstream context gracefully", async () => {
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
-					return {} // No location available
+					return null // No location available
 				},
 			}

@@ -299,6 +364,7 @@ describe("FeedEngine", () => {
 		test("captures errors from fetchContext", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
 				async fetchContext() {
 					throw new Error("Context fetch failed")
 				},
@@ -316,6 +382,10 @@ describe("FeedEngine", () => {
 		test("captures errors from fetchItems", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 				async fetchItems() {
 					throw new Error("Items fetch failed")
 				},
@@ -333,6 +403,7 @@ describe("FeedEngine", () => {
 		test("continues after source error", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
 				async fetchContext() {
 					throw new Error("Failed")
 				},
@@ -340,6 +411,10 @@ describe("FeedEngine", () => {

 			const working: FeedSource = {
 				id: "working",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 				async fetchItems() {
 					return [
 						{
@@ -380,7 +455,10 @@ describe("FeedEngine", () => {
 			await engine.refresh()

 			const context = engine.currentContext()
-			expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
+			expect(contextValue(context, LocationKey)).toEqual({
+				lat: 51.5,
+				lng: -0.1,
+			})
 		})
 	})

@@ -455,4 +533,109 @@ describe("FeedEngine", () => {
 			engine.stop()
 		})
 	})
+
+	describe("executeAction", () => {
+		test("routes action to correct source", async () => {
+			let receivedAction = ""
+			let receivedParams: unknown = {}
+
+			const source: FeedSource = {
+				id: "test-source",
+				async listActions() {
+					return {
+						"do-thing": { id: "do-thing" },
+					}
+				},
+				async executeAction(actionId, params) {
+					receivedAction = actionId
+					receivedParams = params
+				},
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+			await engine.executeAction("test-source", "do-thing", { key: "value" })
+
+			expect(receivedAction).toBe("do-thing")
+			expect(receivedParams).toEqual({ key: "value" })
+		})
+
+		test("throws for unknown source", async () => {
+			const engine = new FeedEngine()
+
+			await expect(engine.executeAction("nonexistent", "action", {})).rejects.toThrow(
+				"Source not found: nonexistent",
+			)
+		})
+
+		test("throws for unknown action on source", async () => {
+			const source: FeedSource = {
+				id: "test-source",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+
+			await expect(engine.executeAction("test-source", "nonexistent", {})).rejects.toThrow(
+				'Action "nonexistent" not found on source "test-source"',
+			)
+		})
+	})
+
+	describe("listActions", () => {
+		test("returns actions for a specific source", async () => {
+			const source: FeedSource = {
+				id: "test-source",
+				async listActions() {
+					return {
+						"action-1": { id: "action-1" },
+						"action-2": { id: "action-2" },
+					}
+				},
+				async executeAction() {},
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+			const actions = await engine.listActions("test-source")
+
+			expect(Object.keys(actions)).toEqual(["action-1", "action-2"])
+		})
+
+		test("throws for unknown source", async () => {
+			const engine = new FeedEngine()
+
+			await expect(engine.listActions("nonexistent")).rejects.toThrow(
+				"Source not found: nonexistent",
+			)
+		})
+
+		test("throws on mismatched action ID", async () => {
+			const source: FeedSource = {
+				id: "bad-source",
+				async listActions() {
+					return {
+						"correct-key": { id: "wrong-id" },
+					}
+				},
+				async executeAction() {},
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+
+			await expect(engine.listActions("bad-source")).rejects.toThrow(
+				'Action ID mismatch on source "bad-source"',
+			)
+		})
+	})
 })
--- a/packages/aris-core/src/feed-engine.ts
+++ b/packages/aris-core/src/feed-engine.ts
@@ -1,3 +1,4 @@
+import type { ActionDefinition } from "./action"
 import type { Context } from "./context"
 import type { FeedItem } from "./feed"
 import type { FeedSource } from "./feed-source"
@@ -89,16 +90,16 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {

 		// Run fetchContext in topological order
 		for (const source of graph.sorted) {
-			if (source.fetchContext) {
-				try {
-					const update = await source.fetchContext(context)
+			try {
+				const update = await source.fetchContext(context)
+				if (update) {
 					context = { ...context, ...update }
-				} catch (err) {
-					errors.push({
-						sourceId: source.id,
-						error: err instanceof Error ? err : new Error(String(err)),
-					})
 				}
+			} catch (err) {
+				errors.push({
+					sourceId: source.id,
+					error: err instanceof Error ? err : new Error(String(err)),
+				})
 			}
 		}

@@ -187,6 +188,44 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		return this.context
 	}

+	/**
+	 * Execute an action on a registered source.
+	 * Validates the action exists before dispatching.
+	 *
+	 * In pull-only mode (before `start()` is called), the action mutates source
+	 * state but does not automatically refresh dependents. Call `refresh()`
+	 * after to propagate changes. In reactive mode (`start()` called), sources
+	 * that push context updates (e.g., LocationSource) will trigger dependent
+	 * refresh automatically.
+	 */
+	async executeAction(sourceId: string, actionId: string, params: unknown): Promise<unknown> {
+		const actions = await this.listActions(sourceId)
+		if (!(actionId in actions)) {
+			throw new Error(`Action "${actionId}" not found on source "${sourceId}"`)
+		}
+		return this.sources.get(sourceId)!.executeAction(actionId, params)
+	}
+
+	/**
+	 * List actions available on a specific source.
+	 * Validates that action definition IDs match their record keys.
+	 */
+	async listActions(sourceId: string): Promise<Record<string, ActionDefinition>> {
+		const source = this.sources.get(sourceId)
+		if (!source) {
+			throw new Error(`Source not found: ${sourceId}`)
+		}
+		const actions = await source.listActions()
+		for (const [key, definition] of Object.entries(actions)) {
+			if (key !== definition.id) {
+				throw new Error(
+					`Action ID mismatch on source "${sourceId}": key "${key}" !== definition.id "${definition.id}"`,
+				)
+			}
+		}
+		return actions
+	}
+
 	private ensureGraph(): SourceGraph {
 		if (!this.graph) {
 			this.graph = buildGraph(Array.from(this.sources.values()))
@@ -208,10 +247,12 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		// Re-run fetchContext for dependents in order
 		for (const id of toRefresh) {
 			const source = graph.sources.get(id)
-			if (source?.fetchContext) {
+			if (source) {
 				try {
 					const update = await source.fetchContext(this.context)
-					this.context = { ...this.context, ...update }
+					if (update) {
+						this.context = { ...this.context, ...update }
+					}
 				} catch {
 					// Errors during reactive updates are logged but don't stop propagation
 				}
@@ -238,7 +279,11 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {

 		items.sort((a, b) => b.priority - a.priority)

-		this.notifySubscribers({ context: this.context, items: items as TItems[], errors })
+		this.notifySubscribers({
+			context: this.context,
+			items: items as TItems[],
+			errors,
+		})
 	}

 	private collectDependents(sourceId: string, graph: SourceGraph): string[] {
--- a/packages/aris-core/src/feed-source.test.ts
+++ b/packages/aris-core/src/feed-source.test.ts
@@ -1,8 +1,18 @@
 import { describe, expect, test } from "bun:test"

-import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
+import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"

-import { contextKey, contextValue } from "./index"
+import { UnknownActionError, contextKey, contextValue } from "./index"
+
+// No-op action methods for test sources
+const noActions = {
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	},
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	},
+}

 // =============================================================================
 // CONTEXT KEYS
@@ -42,6 +52,7 @@ function createLocationSource(): SimulatedLocationSource {

 	return {
 		id: "location",
+		...noActions,

 		onContextUpdate(cb) {
 			callback = cb
@@ -70,10 +81,11 @@ function createWeatherSource(
 	return {
 		id: "weather",
 		dependencies: ["location"],
+		...noActions,

 		async fetchContext(context) {
 			const location = contextValue(context, LocationKey)
-			if (!location) return {}
+			if (!location) return null

 			const weather = await fetchWeather(location)
 			return { [WeatherKey]: weather }
@@ -103,6 +115,11 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 	return {
 		id: "alert",
 		dependencies: ["weather"],
+		...noActions,
+
+		async fetchContext() {
+			return null
+		},

 		async fetchItems(context) {
 			const weather = contextValue(context, WeatherKey)
@@ -194,8 +211,8 @@ async function refreshGraph(graph: SourceGraph): Promise<{ context: Context; ite

 	// Run fetchContext in topological order
 	for (const source of graph.sorted) {
-		if (source.fetchContext) {
-			const update = await source.fetchContext(context)
+		const update = await source.fetchContext(context)
+		if (update) {
 			context = { ...context, ...update }
 		}
 	}
@@ -245,9 +262,15 @@ describe("FeedSource", () => {

 			expect(source.id).toBe("alert")
 			expect(source.dependencies).toEqual(["weather"])
-			expect(source.fetchContext).toBeUndefined()
+			expect(source.fetchContext).toBeDefined()
 			expect(source.fetchItems).toBeDefined()
 		})
+
+		test("source without context returns null from fetchContext", async () => {
+			const source = createAlertSource()
+			const result = await source.fetchContext({ time: new Date() })
+			expect(result).toBeNull()
+		})
 	})

 	describe("graph validation", () => {
@@ -255,6 +278,10 @@ describe("FeedSource", () => {
 			const orphan: FeedSource = {
 				id: "orphan",
 				dependencies: ["nonexistent"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 			}

 			expect(() => buildGraph([orphan])).toThrow(
@@ -263,16 +290,51 @@ describe("FeedSource", () => {
 		})

 		test("detects circular dependencies", () => {
-			const a: FeedSource = { id: "a", dependencies: ["b"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}

 			expect(() => buildGraph([a, b])).toThrow("Circular dependency detected: a → b → a")
 		})

 		test("detects longer cycles", () => {
-			const a: FeedSource = { id: "a", dependencies: ["c"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
-			const c: FeedSource = { id: "c", dependencies: ["b"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["c"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const c: FeedSource = {
+				id: "c",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}

 			expect(() => buildGraph([a, b, c])).toThrow("Circular dependency detected")
 		})
@@ -307,6 +369,7 @@ describe("FeedSource", () => {

 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					order.push("location")
 					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -316,6 +379,7 @@ describe("FeedSource", () => {
 			const weather: FeedSource = {
 				id: "weather",
 				dependencies: ["location"],
+				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
 					const loc = contextValue(ctx, LocationKey)
@@ -339,8 +403,14 @@ describe("FeedSource", () => {
 			const graph = buildGraph([location, weather])
 			const { context } = await refreshGraph(graph)

-			expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
-			expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
+			expect(contextValue(context, LocationKey)).toEqual({
+				lat: 51.5,
+				lng: -0.1,
+			})
+			expect(contextValue(context, WeatherKey)).toEqual({
+				temperature: 20,
+				condition: "sunny",
+			})
 		})

 		test("collects items from all sources", async () => {
@@ -376,12 +446,13 @@ describe("FeedSource", () => {
 		})

 		test("source without location context returns empty items", async () => {
-			// Location source exists but hasn't been updated (returns default 0,0)
+			// Location source exists but hasn't been updated
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					// Simulate no location available
-					return {}
+					return null
 				},
 			}

--- a/packages/aris-core/src/feed-source.ts
+++ b/packages/aris-core/src/feed-source.ts
@@ -1,54 +1,60 @@
+import type { ActionDefinition } from "./action"
 import type { Context } from "./context"
 import type { FeedItem } from "./feed"

 /**
- * Unified interface for sources that provide context and/or feed items.
+ * Unified interface for sources that provide context, feed items, and actions.
 *
- * Sources form a dependency graph - a source declares which other sources
+ * Sources form a dependency graph — a source declares which other sources
 * it depends on, and the graph ensures dependencies are resolved before
 * dependents run.
 *
- * A source may:
- * - Provide context for other sources (implement fetchContext/onContextUpdate)
- * - Produce feed items (implement fetchItems/onItemsUpdate)
- * - Both
+ * Source IDs use reverse domain notation. Built-in sources use `aris.<name>`,
+ * third parties use their own domain (e.g., `com.spotify`).
+ *
+ * Every method maps to a protocol operation for remote source support:
+ * - `id`, `dependencies`       → source/describe
+ * - `listActions()`            → source/listActions
+ * - `executeAction()`          → source/executeAction
+ * - `fetchContext()`           → source/fetchContext
+ * - `fetchItems()`             → source/fetchItems
+ * - `onContextUpdate()`        → source/contextUpdated (notification)
+ * - `onItemsUpdate()`          → source/itemsUpdated (notification)
 *
 * @example
 * ```ts
- * // Location source - provides context only
 * const locationSource: FeedSource = {
- *   id: "location",
- *   fetchContext: async () => {
- *     const pos = await getCurrentPosition()
- *     return { location: { lat: pos.coords.latitude, lng: pos.coords.longitude } }
- *   },
- * }
- *
- * // Weather source - depends on location, provides both context and items
- * const weatherSource: FeedSource<WeatherFeedItem> = {
- *   id: "weather",
- *   dependencies: ["location"],
- *   fetchContext: async (ctx) => {
- *     const weather = await fetchWeather(ctx.location)
- *     return { weather }
- *   },
- *   fetchItems: async (ctx) => {
- *     return createWeatherFeedItems(ctx.weather)
- *   },
+ *   id: "aris.location",
+ *   async listActions() { return { "update-location": { id: "update-location" } } },
+ *   async executeAction(actionId) { throw new UnknownActionError(actionId) },
+ *   async fetchContext() { ... },
 * }
 * ```
 */
 export interface FeedSource<TItem extends FeedItem = FeedItem> {
-	/** Unique identifier for this source */
+	/** Unique identifier for this source in reverse-domain format */
 	readonly id: string

 	/** IDs of sources this source depends on */
 	readonly dependencies?: readonly string[]

+	/**
+	 * List actions this source supports. Empty record if none.
+	 * Maps to: source/listActions
+	 */
+	listActions(): Promise<Record<string, ActionDefinition>>
+
+	/**
+	 * Execute an action by ID. Throws on unknown action or invalid input.
+	 * Maps to: source/executeAction
+	 */
+	executeAction(actionId: string, params: unknown): Promise<unknown>
+
 	/**
 	 * Subscribe to reactive context updates.
 	 * Called when the source can push context changes proactively.
 	 * Returns cleanup function.
+	 * Maps to: source/contextUpdated (notification, source → host)
 	 */
 	onContextUpdate?(
 		callback: (update: Partial<Context>) => void,
@@ -58,19 +64,23 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
 	/**
 	 * Fetch context on-demand.
 	 * Called during manual refresh or initial load.
+	 * Return null if this source cannot provide context.
+	 * Maps to: source/fetchContext
 	 */
-	fetchContext?(context: Context): Promise<Partial<Context>>
+	fetchContext(context: Context): Promise<Partial<Context> | null>

 	/**
 	 * Subscribe to reactive feed item updates.
 	 * Called when the source can push item changes proactively.
 	 * Returns cleanup function.
+	 * Maps to: source/itemsUpdated (notification, source → host)
 	 */
 	onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void

 	/**
 	 * Fetch feed items on-demand.
 	 * Called during manual refresh or when dependencies update.
+	 * Maps to: source/fetchItems
 	 */
 	fetchItems?(context: Context): Promise<TItem[]>
 }
--- a/packages/aris-core/src/index.ts
+++ b/packages/aris-core/src/index.ts
@@ -2,6 +2,10 @@
 export type { Context, ContextKey } from "./context"
 export { contextKey, contextValue } from "./context"

+// Actions
+export type { ActionDefinition } from "./action"
+export { UnknownActionError } from "./action"
+
 // Feed
 export type { FeedItem } from "./feed"

--- a/packages/aris-data-source-weatherkit/src/data-source.test.ts
+++ b/packages/aris-data-source-weatherkit/src/data-source.test.ts
@@ -26,14 +26,18 @@ const createMockContext = (location?: { lat: number; lng: number }): Context =>

 describe("WeatherKitDataSource", () => {
 	test("returns empty array when location is missing", async () => {
-		const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
+		const dataSource = new WeatherKitDataSource({
+			credentials: mockCredentials,
+		})
 		const items = await dataSource.query(createMockContext())

 		expect(items).toEqual([])
 	})

 	test("type is weather-current", () => {
-		const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
+		const dataSource = new WeatherKitDataSource({
+			credentials: mockCredentials,
+		})

 		expect(dataSource.type).toBe(WeatherFeedItemType.current)
 	})
@@ -100,7 +104,9 @@ describe("WeatherKitDataSource with fixture", () => {
 	})

 	test("default limits are applied", () => {
-		const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
+		const dataSource = new WeatherKitDataSource({
+			credentials: mockCredentials,
+		})

 		expect(dataSource["hourlyLimit"]).toBe(12)
 		expect(dataSource["dailyLimit"]).toBe(7)
@@ -163,8 +169,12 @@ describe("query() with mocked client", () => {
 		const dataSource = new WeatherKitDataSource({ client: mockClient })
 		const context = createMockContext({ lat: 37.7749, lng: -122.4194 })

-		const metricItems = await dataSource.query(context, { units: Units.metric })
-		const imperialItems = await dataSource.query(context, { units: Units.imperial })
+		const metricItems = await dataSource.query(context, {
+			units: Units.metric,
+		})
+		const imperialItems = await dataSource.query(context, {
+			units: Units.imperial,
+		})

 		const metricCurrent = metricItems.find((i) => i.type === WeatherFeedItemType.current)
 		const imperialCurrent = imperialItems.find((i) => i.type === WeatherFeedItemType.current)
--- a/packages/aris-source-apple-calendar/fixtures/all-day-event.ics
+++ b/packages/aris-source-apple-calendar/fixtures/all-day-event.ics
@@ -0,0 +1,11 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:all-day-001@test
+DTSTART;VALUE=DATE:20260115
+DTEND;VALUE=DATE:20260116
+SUMMARY:Company Holiday
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR
--- a/packages/aris-source-apple-calendar/fixtures/cancelled-event.ics
+++ b/packages/aris-source-apple-calendar/fixtures/cancelled-event.ics
@@ -0,0 +1,11 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:cancelled-001@test
+DTSTART:20260115T120000Z
+DTEND:20260115T130000Z
+SUMMARY:Cancelled Meeting
+STATUS:CANCELLED
+END:VEVENT
+END:VCALENDAR
--- a/packages/aris-source-apple-calendar/fixtures/minimal-event.ics
+++ b/packages/aris-source-apple-calendar/fixtures/minimal-event.ics
@@ -0,0 +1,10 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:minimal-001@test
+DTSTART:20260115T180000Z
+DTEND:20260115T190000Z
+SUMMARY:Quick Chat
+END:VEVENT
+END:VCALENDAR
--- a/packages/aris-source-apple-calendar/fixtures/recurring-event.ics
+++ b/packages/aris-source-apple-calendar/fixtures/recurring-event.ics
@@ -0,0 +1,20 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:recurring-001@test
+DTSTART:20260115T090000Z
+DTEND:20260115T093000Z
+SUMMARY:Weekly Sync
+RRULE:FREQ=WEEKLY;COUNT=4
+STATUS:CONFIRMED
+END:VEVENT
+BEGIN:VEVENT
+UID:recurring-001@test
+RECURRENCE-ID:20260122T090000Z
+DTSTART:20260122T100000Z
+DTEND:20260122T103000Z
+SUMMARY:Weekly Sync (moved)
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR
--- a/packages/aris-source-apple-calendar/fixtures/single-event.ics
+++ b/packages/aris-source-apple-calendar/fixtures/single-event.ics
@@ -0,0 +1,26 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:single-event-001@test
+DTSTART:20260115T140000Z
+DTEND:20260115T150000Z
+SUMMARY:Team Standup
+LOCATION:Conference Room A
+DESCRIPTION:Daily standup meeting
+STATUS:CONFIRMED
+URL:https://example.com/meeting/123
+ORGANIZER;CN=Alice Smith:mailto:alice@example.com
+ATTENDEE;CN=Bob Jones;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED:mailto:bob@example.com
+ATTENDEE;CN=Carol White;ROLE=OPT-PARTICIPANT;PARTSTAT=TENTATIVE:mailto:carol@example.com
+BEGIN:VALARM
+TRIGGER:-PT15M
+ACTION:DISPLAY
+DESCRIPTION:Reminder
+END:VALARM
+BEGIN:VALARM
+TRIGGER:-PT5M
+ACTION:AUDIO
+END:VALARM
+END:VEVENT
+END:VCALENDAR
--- a/packages/aris-source-apple-calendar/package.json
+++ b/packages/aris-source-apple-calendar/package.json
@@ -0,0 +1,15 @@
+{
+	"name": "@aris/source-apple-calendar",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test ."
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*",
+		"ical.js": "^2.1.0",
+		"tsdav": "^2.1.7"
+	}
+}
--- a/packages/aris-source-apple-calendar/src/calendar-context.ts
+++ b/packages/aris-source-apple-calendar/src/calendar-context.ts
@@ -0,0 +1,24 @@
+import type { ContextKey } from "@aris/core"
+
+import { contextKey } from "@aris/core"
+
+import type { CalendarEventData } from "./types.ts"
+
+/**
+ * Calendar context for downstream sources.
+ *
+ * Provides a snapshot of the user's upcoming events so other sources
+ * can adapt (e.g. a commute source checking if there's a meeting soon).
+ */
+export interface CalendarContext {
+	/** Events happening right now */
+	inProgress: CalendarEventData[]
+	/** Next upcoming event, if any */
+	nextEvent: CalendarEventData | null
+	/** Whether the user has any events today */
+	hasTodayEvents: boolean
+	/** Total number of events today */
+	todayEventCount: number
+}
+
+export const CalendarKey: ContextKey<CalendarContext> = contextKey("calendar")
--- a/packages/aris-source-apple-calendar/src/calendar-source.test.ts
+++ b/packages/aris-source-apple-calendar/src/calendar-source.test.ts
@@ -0,0 +1,473 @@
+import type { Context } from "@aris/core"
+
+import { contextValue } from "@aris/core"
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import type {
+	CalendarCredentialProvider,
+	CalendarCredentials,
+	CalendarDAVCalendar,
+	CalendarDAVClient,
+	CalendarDAVObject,
+	CalendarEventData,
+} from "./types.ts"
+
+import { CalendarKey } from "./calendar-context.ts"
+import { CalendarSource, computePriority } from "./calendar-source.ts"
+
+function loadFixture(name: string): string {
+	return readFileSync(join(import.meta.dir, "..", "fixtures", name), "utf-8")
+}
+
+function createContext(time: Date): Context {
+	return { time }
+}
+
+const mockCredentials: CalendarCredentials = {
+	accessToken: "mock-access-token",
+	refreshToken: "mock-refresh-token",
+	expiresAt: Date.now() + 3600000,
+	tokenUrl: "https://appleid.apple.com/auth/token",
+	clientId: "com.example.aris",
+	clientSecret: "mock-secret",
+}
+
+class NullCredentialProvider implements CalendarCredentialProvider {
+	async fetchCredentials(_userId: string): Promise<CalendarCredentials | null> {
+		return null
+	}
+}
+
+class MockCredentialProvider implements CalendarCredentialProvider {
+	async fetchCredentials(_userId: string): Promise<CalendarCredentials | null> {
+		return mockCredentials
+	}
+}
+
+class MockDAVClient implements CalendarDAVClient {
+	credentials: Record<string, unknown> = {}
+	fetchCalendarsCallCount = 0
+	private calendars: CalendarDAVCalendar[]
+	private objectsByCalendarUrl: Record<string, CalendarDAVObject[]>
+
+	constructor(
+		calendars: CalendarDAVCalendar[],
+		objectsByCalendarUrl: Record<string, CalendarDAVObject[]>,
+	) {
+		this.calendars = calendars
+		this.objectsByCalendarUrl = objectsByCalendarUrl
+	}
+
+	async login(): Promise<void> {}
+
+	async fetchCalendars(): Promise<CalendarDAVCalendar[]> {
+		this.fetchCalendarsCallCount++
+		return this.calendars
+	}
+
+	async fetchCalendarObjects(params: {
+		calendar: CalendarDAVCalendar
+		timeRange: { start: string; end: string }
+	}): Promise<CalendarDAVObject[]> {
+		return this.objectsByCalendarUrl[params.calendar.url] ?? []
+	}
+}
+
+describe("CalendarSource", () => {
+	test("has correct id", () => {
+		const source = new CalendarSource(new NullCredentialProvider(), "user-1")
+		expect(source.id).toBe("aris.apple-calendar")
+	})
+
+	test("returns empty array when credentials are null", async () => {
+		const source = new CalendarSource(new NullCredentialProvider(), "user-1")
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items).toEqual([])
+	})
+
+	test("returns empty array when no calendars exist", async () => {
+		const client = new MockDAVClient([], {})
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items).toEqual([])
+	})
+
+	test("returns feed items from a single calendar", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(1)
+		expect(items[0]!.type).toBe("calendar-event")
+		expect(items[0]!.id).toBe("calendar-event-single-event-001@test")
+		expect(items[0]!.data.title).toBe("Team Standup")
+		expect(items[0]!.data.location).toBe("Conference Room A")
+		expect(items[0]!.data.calendarName).toBe("Work")
+		expect(items[0]!.data.attendees).toHaveLength(2)
+		expect(items[0]!.data.alarms).toHaveLength(2)
+	})
+
+	test("returns feed items from multiple calendars", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+			"/cal/personal": [
+				{
+					url: "/cal/personal/event2.ics",
+					data: loadFixture("all-day-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient(
+			[
+				{ url: "/cal/work", displayName: "Work" },
+				{ url: "/cal/personal", displayName: "Personal" },
+			],
+			objects,
+		)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(2)
+
+		const standup = items.find((i) => i.data.title === "Team Standup")
+		const holiday = items.find((i) => i.data.title === "Company Holiday")
+
+		expect(standup).toBeDefined()
+		expect(standup!.data.calendarName).toBe("Work")
+
+		expect(holiday).toBeDefined()
+		expect(holiday!.data.calendarName).toBe("Personal")
+		expect(holiday!.data.isAllDay).toBe(true)
+	})
+
+	test("skips objects with non-string data", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ url: "/cal/work/bad.ics", data: 12345 },
+				{ url: "/cal/work/empty.ics" },
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items).toHaveLength(1)
+		expect(items[0]!.data.title).toBe("Team Standup")
+	})
+
+	test("uses context time as feed item timestamp", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const now = new Date("2026-01-15T12:00:00Z")
+		const items = await source.fetchItems(createContext(now))
+		expect(items[0]!.timestamp).toEqual(now)
+	})
+
+	test("assigns priority based on event proximity", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") },
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		// 2 hours before the event at 14:00
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		const standup = items.find((i) => i.data.title === "Team Standup")
+		const holiday = items.find((i) => i.data.title === "Company Holiday")
+
+		expect(standup!.priority).toBe(0.7) // within 2 hours
+		expect(holiday!.priority).toBe(0.3) // all-day
+	})
+
+	test("handles calendar with non-string displayName", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/weird": [
+				{
+					url: "/cal/weird/event1.ics",
+					data: loadFixture("minimal-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient(
+			[{ url: "/cal/weird", displayName: { _cdata: "Weird Calendar" } }],
+			objects,
+		)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items[0]!.data.calendarName).toBeNull()
+	})
+
+	test("handles recurring events with exceptions", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{
+					url: "/cal/work/recurring.ics",
+					data: loadFixture("recurring-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T08:00:00Z")))
+
+		expect(items).toHaveLength(2)
+
+		const base = items.find((i) => i.data.title === "Weekly Sync")
+		const exception = items.find((i) => i.data.title === "Weekly Sync (moved)")
+
+		expect(base).toBeDefined()
+		expect(base!.data.recurrenceId).toBeNull()
+
+		expect(exception).toBeDefined()
+		expect(exception!.data.recurrenceId).not.toBeNull()
+		expect(exception!.id).toContain("-")
+	})
+
+	test("caches events within the same refresh cycle", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const context = createContext(new Date("2026-01-15T12:00:00Z"))
+
+		await source.fetchContext(context)
+		await source.fetchItems(context)
+
+		// Same context.time reference — fetchEvents should only hit the client once
+		expect(client.fetchCalendarsCallCount).toBe(1)
+	})
+
+	test("refetches events for a different context time", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		await source.fetchItems(createContext(new Date("2026-01-15T13:00:00Z")))
+
+		// Different context.time references — should fetch twice
+		expect(client.fetchCalendarsCallCount).toBe(2)
+	})
+})
+
+describe("CalendarSource.fetchContext", () => {
+	test("returns empty context when credentials are null", async () => {
+		const source = new CalendarSource(new NullCredentialProvider(), "user-1")
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar).toBeDefined()
+		expect(calendar!.inProgress).toEqual([])
+		expect(calendar!.nextEvent).toBeNull()
+		expect(calendar!.hasTodayEvents).toBe(false)
+		expect(calendar!.todayEventCount).toBe(0)
+	})
+
+	test("identifies in-progress events", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		// 14:30 is during the 14:00-15:00 event
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T14:30:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.inProgress).toHaveLength(1)
+		expect(calendar!.inProgress[0]!.title).toBe("Team Standup")
+	})
+
+	test("identifies next upcoming event", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		// 12:00 is before the 14:00 event
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.inProgress).toHaveLength(0)
+		expect(calendar!.nextEvent).not.toBeNull()
+		expect(calendar!.nextEvent!.title).toBe("Team Standup")
+	})
+
+	test("excludes all-day events from inProgress and nextEvent", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.inProgress).toHaveLength(0)
+		expect(calendar!.nextEvent).toBeNull()
+		expect(calendar!.hasTodayEvents).toBe(true)
+		expect(calendar!.todayEventCount).toBe(1)
+	})
+
+	test("counts all events including all-day in todayEventCount", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") },
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.todayEventCount).toBe(2)
+		expect(calendar!.hasTodayEvents).toBe(true)
+	})
+})
+
+describe("computePriority", () => {
+	const now = new Date("2026-01-15T12:00:00Z")
+
+	function makeEvent(overrides: Partial<CalendarEventData>): CalendarEventData {
+		return {
+			uid: "test-uid",
+			title: "Test",
+			startDate: new Date("2026-01-15T14:00:00Z"),
+			endDate: new Date("2026-01-15T15:00:00Z"),
+			isAllDay: false,
+			location: null,
+			description: null,
+			calendarName: null,
+			status: null,
+			url: null,
+			organizer: null,
+			attendees: [],
+			alarms: [],
+			recurrenceId: null,
+			...overrides,
+		}
+	}
+
+	test("all-day events get priority 0.3", () => {
+		const event = makeEvent({ isAllDay: true })
+		expect(computePriority(event, now)).toBe(0.3)
+	})
+
+	test("events starting within 30 minutes get priority 0.9", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T12:20:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.9)
+	})
+
+	test("events starting exactly at 30 minutes get priority 0.9", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T12:30:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.9)
+	})
+
+	test("events starting within 2 hours get priority 0.7", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T13:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.7)
+	})
+
+	test("events later today get priority 0.5", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T20:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.5)
+	})
+
+	test("in-progress events get priority 0.8", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T11:00:00Z"),
+			endDate: new Date("2026-01-15T13:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.8)
+	})
+
+	test("fully past events get priority 0.2", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T09:00:00Z"),
+			endDate: new Date("2026-01-15T10:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.2)
+	})
+
+	test("events on future days get priority 0.2", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-16T10:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.2)
+	})
+
+	test("priority boundaries are correct", () => {
+		// 31 minutes from now should be 0.7 (within 2 hours, not within 30 min)
+		const event31min = makeEvent({
+			startDate: new Date("2026-01-15T12:31:00Z"),
+		})
+		expect(computePriority(event31min, now)).toBe(0.7)
+
+		// 2 hours 1 minute from now should be 0.5 (later today, not within 2 hours)
+		const event2h1m = makeEvent({
+			startDate: new Date("2026-01-15T14:01:00Z"),
+		})
+		expect(computePriority(event2h1m, now)).toBe(0.5)
+	})
+})
--- a/packages/aris-source-apple-calendar/src/calendar-source.ts
+++ b/packages/aris-source-apple-calendar/src/calendar-source.ts
@@ -0,0 +1,251 @@
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+import { UnknownActionError } from "@aris/core"
+
+import { DAVClient } from "tsdav"
+
+import type {
+	CalendarCredentialProvider,
+	CalendarCredentials,
+	CalendarDAVClient,
+	CalendarEventData,
+	CalendarFeedItem,
+} from "./types.ts"
+
+export interface CalendarSourceOptions {
+	/** Number of additional days beyond today to fetch. Default: 0 (today only). */
+	lookAheadDays?: number
+	/** Optional DAVClient instance for testing. Uses tsdav DAVClient by default. */
+	davClient?: CalendarDAVClient
+}
+
+import { CalendarKey, type CalendarContext } from "./calendar-context.ts"
+import { parseICalEvents } from "./ical-parser.ts"
+
+const ICLOUD_CALDAV_URL = "https://caldav.icloud.com"
+const DEFAULT_LOOK_AHEAD_DAYS = 0
+
+/**
+ * A FeedSource that fetches Apple Calendar events via CalDAV.
+ *
+ * Credentials are provided by an injected CalendarCredentialProvider.
+ * The server is responsible for managing OAuth tokens and storage.
+ *
+ * @example
+ * ```ts
+ * const source = new CalendarSource(credentialProvider, "user-123")
+ * const engine = new FeedEngine()
+ * engine.register(source)
+ * ```
+ */
+export class CalendarSource implements FeedSource<CalendarFeedItem> {
+	readonly id = "aris.apple-calendar"
+
+	private readonly credentialProvider: CalendarCredentialProvider
+	private readonly userId: string
+	private readonly lookAheadDays: number
+	private readonly injectedClient: CalendarDAVClient | null
+	private davClient: CalendarDAVClient | null = null
+	private lastAccessToken: string | null = null
+	private cachedEvents: { time: Date; events: CalendarEventData[] } | null = null
+
+	constructor(
+		credentialProvider: CalendarCredentialProvider,
+		userId: string,
+		options?: CalendarSourceOptions,
+	) {
+		this.credentialProvider = credentialProvider
+		this.userId = userId
+		this.lookAheadDays = options?.lookAheadDays ?? DEFAULT_LOOK_AHEAD_DAYS
+		this.injectedClient = options?.davClient ?? null
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	}
+
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	}
+
+	async fetchContext(context: Context): Promise<Partial<Context> | null> {
+		const events = await this.fetchEvents(context)
+		if (events.length === 0) {
+			return {
+				[CalendarKey]: {
+					inProgress: [],
+					nextEvent: null,
+					hasTodayEvents: false,
+					todayEventCount: 0,
+				},
+			}
+		}
+
+		const now = context.time
+		const inProgress = events.filter((e) => !e.isAllDay && e.startDate <= now && e.endDate > now)
+
+		const upcoming = events
+			.filter((e) => !e.isAllDay && e.startDate > now)
+			.sort((a, b) => a.startDate.getTime() - b.startDate.getTime())
+
+		const calendarContext: CalendarContext = {
+			inProgress,
+			nextEvent: upcoming[0] ?? null,
+			hasTodayEvents: events.length > 0,
+			todayEventCount: events.length,
+		}
+
+		return { [CalendarKey]: calendarContext }
+	}
+
+	async fetchItems(context: Context): Promise<CalendarFeedItem[]> {
+		const now = context.time
+		const events = await this.fetchEvents(context)
+		return events.map((event) => createFeedItem(event, now))
+	}
+
+	private async fetchEvents(context: Context): Promise<CalendarEventData[]> {
+		if (this.cachedEvents && this.cachedEvents.time === context.time) {
+			return this.cachedEvents.events
+		}
+
+		const credentials = await this.credentialProvider.fetchCredentials(this.userId)
+		if (!credentials) {
+			return []
+		}
+
+		const client = await this.connectClient(credentials)
+		const calendars = await client.fetchCalendars()
+
+		const { start, end } = computeTimeRange(context.time, this.lookAheadDays)
+
+		const results = await Promise.allSettled(
+			calendars.map(async (calendar) => {
+				const objects = await client.fetchCalendarObjects({
+					calendar,
+					timeRange: {
+						start: start.toISOString(),
+						end: end.toISOString(),
+					},
+				})
+				// tsdav types displayName as string | Record<string, unknown> | undefined
+				// because the XML parser can return an object for some responses
+				const calendarName = typeof calendar.displayName === "string" ? calendar.displayName : null
+				return { objects, calendarName }
+			}),
+		)
+
+		const allEvents: CalendarEventData[] = []
+		for (const result of results) {
+			if (result.status !== "fulfilled") continue
+			const { objects, calendarName } = result.value
+			for (const obj of objects) {
+				if (typeof obj.data !== "string") continue
+
+				const events = parseICalEvents(obj.data, calendarName)
+				for (const event of events) {
+					allEvents.push(event)
+				}
+			}
+		}
+
+		this.cachedEvents = { time: context.time, events: allEvents }
+		return allEvents
+	}
+
+	/**
+	 * Returns a ready-to-use DAVClient. Creates and logs in a new client
+	 * on first call; reuses the existing one on subsequent calls, updating
+	 * credentials if the access token has changed.
+	 */
+	private async connectClient(credentials: CalendarCredentials): Promise<CalendarDAVClient> {
+		if (this.injectedClient) {
+			return this.injectedClient
+		}
+
+		const davCredentials = {
+			tokenUrl: credentials.tokenUrl,
+			refreshToken: credentials.refreshToken,
+			accessToken: credentials.accessToken,
+			expiration: credentials.expiresAt,
+			clientId: credentials.clientId,
+			clientSecret: credentials.clientSecret,
+		}
+
+		if (!this.davClient) {
+			this.davClient = new DAVClient({
+				serverUrl: ICLOUD_CALDAV_URL,
+				credentials: davCredentials,
+				authMethod: "Oauth",
+				defaultAccountType: "caldav",
+			})
+			await this.davClient.login()
+			this.lastAccessToken = credentials.accessToken
+			return this.davClient
+		}
+
+		if (credentials.accessToken !== this.lastAccessToken) {
+			this.davClient.credentials = davCredentials
+			this.lastAccessToken = credentials.accessToken
+		}
+
+		return this.davClient
+	}
+}
+
+function computeTimeRange(now: Date, lookAheadDays: number): { start: Date; end: Date } {
+	const start = new Date(now)
+	start.setUTCHours(0, 0, 0, 0)
+
+	const end = new Date(start)
+	end.setUTCDate(end.getUTCDate() + 1 + lookAheadDays)
+
+	return { start, end }
+}
+
+export function computePriority(event: CalendarEventData, now: Date): number {
+	if (event.isAllDay) {
+		return 0.3
+	}
+
+	const msUntilStart = event.startDate.getTime() - now.getTime()
+
+	// Event already started
+	if (msUntilStart < 0) {
+		const isInProgress = now.getTime() < event.endDate.getTime()
+		// Currently happening events are high priority; fully past events are low
+		return isInProgress ? 0.8 : 0.2
+	}
+
+	// Starting within 30 minutes
+	if (msUntilStart <= 30 * 60 * 1000) {
+		return 0.9
+	}
+
+	// Starting within 2 hours
+	if (msUntilStart <= 2 * 60 * 60 * 1000) {
+		return 0.7
+	}
+
+	// Later today (within 24 hours from start of day)
+	const startOfDay = new Date(now)
+	startOfDay.setUTCHours(0, 0, 0, 0)
+	const endOfDay = new Date(startOfDay)
+	endOfDay.setUTCDate(endOfDay.getUTCDate() + 1)
+
+	if (event.startDate.getTime() < endOfDay.getTime()) {
+		return 0.5
+	}
+
+	// Future days
+	return 0.2
+}
+
+function createFeedItem(event: CalendarEventData, now: Date): CalendarFeedItem {
+	return {
+		id: `calendar-event-${event.uid}${event.recurrenceId ? `-${event.recurrenceId}` : ""}`,
+		type: "calendar-event",
+		priority: computePriority(event, now),
+		timestamp: now,
+		data: event,
+	}
+}
--- a/packages/aris-source-apple-calendar/src/ical-parser.test.ts
+++ b/packages/aris-source-apple-calendar/src/ical-parser.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { parseICalEvents } from "./ical-parser.ts"
+
+function loadFixture(name: string): string {
+	return readFileSync(join(import.meta.dir, "..", "fixtures", name), "utf-8")
+}
+
+describe("parseICalEvents", () => {
+	test("parses a full event with all fields", () => {
+		const events = parseICalEvents(loadFixture("single-event.ics"), "Work")
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.uid).toBe("single-event-001@test")
+		expect(event.title).toBe("Team Standup")
+		expect(event.startDate).toEqual(new Date("2026-01-15T14:00:00Z"))
+		expect(event.endDate).toEqual(new Date("2026-01-15T15:00:00Z"))
+		expect(event.isAllDay).toBe(false)
+		expect(event.location).toBe("Conference Room A")
+		expect(event.description).toBe("Daily standup meeting")
+		expect(event.calendarName).toBe("Work")
+		expect(event.status).toBe("confirmed")
+		expect(event.url).toBe("https://example.com/meeting/123")
+		expect(event.organizer).toBe("Alice Smith")
+		expect(event.recurrenceId).toBeNull()
+
+		expect(event.attendees).toHaveLength(2)
+		expect(event.attendees[0]).toEqual({
+			name: "Bob Jones",
+			email: "bob@example.com",
+			role: "required",
+			status: "accepted",
+		})
+		expect(event.attendees[1]).toEqual({
+			name: "Carol White",
+			email: "carol@example.com",
+			role: "optional",
+			status: "tentative",
+		})
+
+		expect(event.alarms).toHaveLength(2)
+		expect(event.alarms[0]).toEqual({ trigger: "-PT15M", action: "DISPLAY" })
+		expect(event.alarms[1]).toEqual({ trigger: "-PT5M", action: "AUDIO" })
+	})
+
+	test("parses an all-day event with optional fields as null", () => {
+		const events = parseICalEvents(loadFixture("all-day-event.ics"), null)
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.isAllDay).toBe(true)
+		expect(event.title).toBe("Company Holiday")
+		expect(event.calendarName).toBeNull()
+		expect(event.location).toBeNull()
+		expect(event.description).toBeNull()
+		expect(event.url).toBeNull()
+		expect(event.organizer).toBeNull()
+		expect(event.attendees).toEqual([])
+		expect(event.alarms).toEqual([])
+	})
+
+	test("parses recurring event with exception", () => {
+		const events = parseICalEvents(loadFixture("recurring-event.ics"), "Team")
+
+		expect(events).toHaveLength(2)
+		expect(events[0]!.uid).toBe("recurring-001@test")
+		expect(events[1]!.uid).toBe("recurring-001@test")
+
+		const base = events.find((e) => e.title === "Weekly Sync")
+		expect(base).toBeDefined()
+		expect(base!.recurrenceId).toBeNull()
+
+		const exception = events.find((e) => e.title === "Weekly Sync (moved)")
+		expect(exception).toBeDefined()
+		expect(exception!.recurrenceId).not.toBeNull()
+	})
+
+	test("parses minimal event with defaults", () => {
+		const events = parseICalEvents(loadFixture("minimal-event.ics"), null)
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.uid).toBe("minimal-001@test")
+		expect(event.title).toBe("Quick Chat")
+		expect(event.startDate).toEqual(new Date("2026-01-15T18:00:00Z"))
+		expect(event.endDate).toEqual(new Date("2026-01-15T19:00:00Z"))
+		expect(event.location).toBeNull()
+		expect(event.description).toBeNull()
+		expect(event.status).toBeNull()
+		expect(event.url).toBeNull()
+		expect(event.organizer).toBeNull()
+		expect(event.attendees).toEqual([])
+		expect(event.alarms).toEqual([])
+		expect(event.recurrenceId).toBeNull()
+	})
+
+	test("parses cancelled status", () => {
+		const events = parseICalEvents(loadFixture("cancelled-event.ics"), null)
+		expect(events[0]!.status).toBe("cancelled")
+	})
+})
--- a/packages/aris-source-apple-calendar/src/ical-parser.ts
+++ b/packages/aris-source-apple-calendar/src/ical-parser.ts
@@ -0,0 +1,150 @@
+import ICAL from "ical.js"
+
+import {
+	AttendeeRole,
+	AttendeeStatus,
+	CalendarEventStatus,
+	type CalendarAlarm,
+	type CalendarAttendee,
+	type CalendarEventData,
+} from "./types.ts"
+
+/**
+ * Parses a raw iCalendar string and extracts all VEVENT components
+ * into CalendarEventData objects.
+ *
+ * @param icsData - Raw iCalendar string from a CalDAV response
+ * @param calendarName - Display name of the calendar this event belongs to
+ */
+export function parseICalEvents(icsData: string, calendarName: string | null): CalendarEventData[] {
+	const jcal = ICAL.parse(icsData)
+	const comp = new ICAL.Component(jcal)
+	const vevents = comp.getAllSubcomponents("vevent")
+
+	return vevents.map((vevent: InstanceType<typeof ICAL.Component>) =>
+		parseVEvent(vevent, calendarName),
+	)
+}
+
+function parseVEvent(
+	vevent: InstanceType<typeof ICAL.Component>,
+	calendarName: string | null,
+): CalendarEventData {
+	const event = new ICAL.Event(vevent)
+
+	return {
+		uid: event.uid ?? "",
+		title: event.summary ?? "",
+		startDate: event.startDate?.toJSDate() ?? new Date(0),
+		endDate: event.endDate?.toJSDate() ?? new Date(0),
+		isAllDay: event.startDate?.isDate ?? false,
+		location: event.location ?? null,
+		description: event.description ?? null,
+		calendarName,
+		status: parseStatus(asStringOrNull(vevent.getFirstPropertyValue("status"))),
+		url: asStringOrNull(vevent.getFirstPropertyValue("url")),
+		organizer: parseOrganizer(asStringOrNull(event.organizer), vevent),
+		attendees: parseAttendees(Array.isArray(event.attendees) ? event.attendees : []),
+		alarms: parseAlarms(vevent),
+		recurrenceId: event.recurrenceId ? event.recurrenceId.toString() : null,
+	}
+}
+
+function parseStatus(raw: string | null): CalendarEventStatus | null {
+	if (!raw) return null
+	switch (raw.toLowerCase()) {
+		case "confirmed":
+			return CalendarEventStatus.Confirmed
+		case "tentative":
+			return CalendarEventStatus.Tentative
+		case "cancelled":
+			return CalendarEventStatus.Cancelled
+		default:
+			return null
+	}
+}
+
+function parseOrganizer(
+	value: string | null,
+	vevent: InstanceType<typeof ICAL.Component>,
+): string | null {
+	if (!value) return null
+
+	// Try CN parameter first
+	const prop = vevent.getFirstProperty("organizer")
+	if (prop) {
+		const cn = prop.getParameter("cn") as string | undefined
+		if (cn) return cn
+	}
+
+	// Fall back to mailto: value
+	return value.replace(/^mailto:/i, "")
+}
+
+function parseAttendees(properties: unknown[]): CalendarAttendee[] {
+	if (properties.length === 0) return []
+
+	return properties.map((prop) => {
+		const p = prop as InstanceType<typeof ICAL.Property>
+		const value = asStringOrNull(p.getFirstValue())
+		const cn = asStringOrNull(p.getParameter("cn"))
+		const role = asStringOrNull(p.getParameter("role"))
+		const partstat = asStringOrNull(p.getParameter("partstat"))
+
+		return {
+			name: cn,
+			email: value ? value.replace(/^mailto:/i, "") : null,
+			role: parseAttendeeRole(role),
+			status: parseAttendeeStatus(partstat),
+		}
+	})
+}
+
+function parseAttendeeRole(raw: string | null): AttendeeRole | null {
+	if (!raw) return null
+	switch (raw.toUpperCase()) {
+		case "CHAIR":
+			return AttendeeRole.Chair
+		case "REQ-PARTICIPANT":
+			return AttendeeRole.Required
+		case "OPT-PARTICIPANT":
+			return AttendeeRole.Optional
+		default:
+			return null
+	}
+}
+
+function parseAttendeeStatus(raw: string | null): AttendeeStatus | null {
+	if (!raw) return null
+	switch (raw.toUpperCase()) {
+		case "ACCEPTED":
+			return AttendeeStatus.Accepted
+		case "DECLINED":
+			return AttendeeStatus.Declined
+		case "TENTATIVE":
+			return AttendeeStatus.Tentative
+		case "NEEDS-ACTION":
+			return AttendeeStatus.NeedsAction
+		default:
+			return null
+	}
+}
+
+function parseAlarms(vevent: InstanceType<typeof ICAL.Component>): CalendarAlarm[] {
+	const valarms = vevent.getAllSubcomponents("valarm")
+	if (!valarms || valarms.length === 0) return []
+
+	return valarms.map((valarm: InstanceType<typeof ICAL.Component>) => {
+		const trigger = valarm.getFirstPropertyValue("trigger")
+		const action = asStringOrNull(valarm.getFirstPropertyValue("action"))
+
+		return {
+			trigger: trigger ? trigger.toString() : "",
+			action: action ?? "DISPLAY",
+		}
+	})
+}
+
+function asStringOrNull(value: unknown): string | null {
+	return typeof value === "string" ? value : null
+}
--- a/packages/aris-source-apple-calendar/src/index.ts
+++ b/packages/aris-source-apple-calendar/src/index.ts
@@ -0,0 +1,16 @@
+export { CalendarKey, type CalendarContext } from "./calendar-context.ts"
+export { CalendarSource, type CalendarSourceOptions } from "./calendar-source.ts"
+export {
+	CalendarEventStatus,
+	AttendeeRole,
+	AttendeeStatus,
+	type CalendarCredentials,
+	type CalendarCredentialProvider,
+	type CalendarDAVClient,
+	type CalendarDAVCalendar,
+	type CalendarDAVObject,
+	type CalendarAttendee,
+	type CalendarAlarm,
+	type CalendarEventData,
+	type CalendarFeedItem,
+} from "./types.ts"
--- a/packages/aris-source-apple-calendar/src/types.ts
+++ b/packages/aris-source-apple-calendar/src/types.ts
@@ -0,0 +1,101 @@
+import type { FeedItem } from "@aris/core"
+
+// -- Credential provider --
+
+export interface CalendarCredentials {
+	accessToken: string
+	refreshToken: string
+	/** Unix timestamp in milliseconds when the access token expires */
+	expiresAt: number
+	tokenUrl: string
+	clientId: string
+	clientSecret: string
+}
+
+export interface CalendarCredentialProvider {
+	fetchCredentials(userId: string): Promise<CalendarCredentials | null>
+}
+
+// -- Feed item types --
+
+export const CalendarEventStatus = {
+	Confirmed: "confirmed",
+	Tentative: "tentative",
+	Cancelled: "cancelled",
+} as const
+
+export type CalendarEventStatus = (typeof CalendarEventStatus)[keyof typeof CalendarEventStatus]
+
+export const AttendeeRole = {
+	Chair: "chair",
+	Required: "required",
+	Optional: "optional",
+} as const
+
+export type AttendeeRole = (typeof AttendeeRole)[keyof typeof AttendeeRole]
+
+export const AttendeeStatus = {
+	Accepted: "accepted",
+	Declined: "declined",
+	Tentative: "tentative",
+	NeedsAction: "needs-action",
+} as const
+
+export type AttendeeStatus = (typeof AttendeeStatus)[keyof typeof AttendeeStatus]
+
+export interface CalendarAttendee {
+	name: string | null
+	email: string | null
+	role: AttendeeRole | null
+	status: AttendeeStatus | null
+}
+
+export interface CalendarAlarm {
+	/** ISO 8601 duration relative to event start, e.g. "-PT15M" */
+	trigger: string
+	/** e.g. "DISPLAY", "AUDIO" */
+	action: string
+}
+
+export interface CalendarEventData extends Record<string, unknown> {
+	uid: string
+	title: string
+	startDate: Date
+	endDate: Date
+	isAllDay: boolean
+	location: string | null
+	description: string | null
+	calendarName: string | null
+	status: CalendarEventStatus | null
+	url: string | null
+	organizer: string | null
+	attendees: CalendarAttendee[]
+	alarms: CalendarAlarm[]
+	recurrenceId: string | null
+}
+
+export type CalendarFeedItem = FeedItem<"calendar-event", CalendarEventData>
+
+// -- DAV client interface --
+
+export interface CalendarDAVObject {
+	data?: unknown
+	etag?: string
+	url: string
+}
+
+export interface CalendarDAVCalendar {
+	displayName?: string | Record<string, unknown>
+	url: string
+}
+
+/** Subset of DAVClient used by CalendarSource. */
+export interface CalendarDAVClient {
+	login(): Promise<void>
+	fetchCalendars(): Promise<CalendarDAVCalendar[]>
+	fetchCalendarObjects(params: {
+		calendar: CalendarDAVCalendar
+		timeRange: { start: string; end: string }
+	}): Promise<CalendarDAVObject[]>
+	credentials: Record<string, unknown>
+}
--- a/packages/aris-source-google-calendar/fixtures/events.json
+++ b/packages/aris-source-google-calendar/fixtures/events.json
@@ -0,0 +1,72 @@
+{
+	"kind": "calendar#events",
+	"summary": "primary",
+	"items": [
+		{
+			"id": "evt-ongoing",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-ongoing",
+			"summary": "Team Standup",
+			"description": "Daily standup meeting",
+			"location": "Room 3A",
+			"start": {
+				"dateTime": "2026-01-20T09:30:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T10:15:00Z"
+			}
+		},
+		{
+			"id": "evt-soon",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-soon",
+			"summary": "1:1 with Manager",
+			"start": {
+				"dateTime": "2026-01-20T10:10:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T10:40:00Z"
+			}
+		},
+		{
+			"id": "evt-later",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-later",
+			"summary": "Design Review",
+			"description": "Review new dashboard designs",
+			"location": "Conference Room B",
+			"start": {
+				"dateTime": "2026-01-20T14:00:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T15:00:00Z"
+			}
+		},
+		{
+			"id": "evt-tentative",
+			"status": "tentative",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-tentative",
+			"summary": "Lunch with Alex",
+			"location": "Cafe Nero",
+			"start": {
+				"dateTime": "2026-01-20T12:00:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T13:00:00Z"
+			}
+		},
+		{
+			"id": "evt-allday",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-allday",
+			"summary": "Company Holiday",
+			"description": "Office closed",
+			"start": {
+				"date": "2026-01-20"
+			},
+			"end": {
+				"date": "2026-01-21"
+			}
+		}
+	]
+}
--- a/packages/aris-source-google-calendar/package.json
+++ b/packages/aris-source-google-calendar/package.json
@@ -0,0 +1,14 @@
+{
+	"name": "@aris/source-google-calendar",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test ."
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*",
+		"arktype": "^2.1.0"
+	}
+}
--- a/packages/aris-source-google-calendar/src/calendar-context.ts
+++ b/packages/aris-source-google-calendar/src/calendar-context.ts
@@ -0,0 +1,13 @@
+import type { ContextKey } from "@aris/core"
+
+import { contextKey } from "@aris/core"
+
+export interface NextEvent {
+	title: string
+	startTime: Date
+	endTime: Date
+	minutesUntilStart: number
+	location: string | null
+}
+
+export const NextEventKey: ContextKey<NextEvent> = contextKey("nextEvent")
--- a/packages/aris-source-google-calendar/src/feed-items.ts
+++ b/packages/aris-source-google-calendar/src/feed-items.ts
@@ -0,0 +1,22 @@
+import type { FeedItem } from "@aris/core"
+
+import type { CalendarEventData } from "./types"
+
+export const CalendarFeedItemType = {
+	event: "calendar-event",
+	allDay: "calendar-all-day",
+} as const
+
+export type CalendarFeedItemType = (typeof CalendarFeedItemType)[keyof typeof CalendarFeedItemType]
+
+export interface CalendarEventFeedItem extends FeedItem<
+	typeof CalendarFeedItemType.event,
+	CalendarEventData
+> {}
+
+export interface CalendarAllDayFeedItem extends FeedItem<
+	typeof CalendarFeedItemType.allDay,
+	CalendarEventData
+> {}
+
+export type CalendarFeedItem = CalendarEventFeedItem | CalendarAllDayFeedItem
--- a/packages/aris-source-google-calendar/src/google-calendar-api.ts
+++ b/packages/aris-source-google-calendar/src/google-calendar-api.ts
@@ -0,0 +1,122 @@
+// Google Calendar REST API v3 client
+// https://developers.google.com/calendar/api/v3/reference/events/list
+
+import { type } from "arktype"
+
+import type {
+	ApiCalendarEvent,
+	GoogleCalendarClient,
+	GoogleOAuthProvider,
+	ListEventsOptions,
+} from "./types"
+
+import { EventStatus } from "./types"
+
+const eventStatusSchema = type.enumerated(
+	EventStatus.Confirmed,
+	EventStatus.Tentative,
+	EventStatus.Cancelled,
+)
+
+const eventDateTimeSchema = type({
+	"dateTime?": "string",
+	"date?": "string",
+	"timeZone?": "string",
+})
+
+const eventSchema = type({
+	id: "string",
+	status: eventStatusSchema,
+	htmlLink: "string",
+	"summary?": "string",
+	"description?": "string",
+	"location?": "string",
+	start: eventDateTimeSchema,
+	end: eventDateTimeSchema,
+})
+
+const calendarListEntrySchema = type({
+	id: "string",
+})
+
+const calendarListResponseSchema = type({
+	"items?": calendarListEntrySchema.array(),
+	"nextPageToken?": "string",
+})
+
+const eventsResponseSchema = type({
+	"items?": eventSchema.array(),
+	"nextPageToken?": "string",
+})
+
+export class DefaultGoogleCalendarClient implements GoogleCalendarClient {
+	private static readonly API_BASE = "https://www.googleapis.com/calendar/v3"
+
+	private readonly oauthProvider: GoogleOAuthProvider
+
+	constructor(oauthProvider: GoogleOAuthProvider) {
+		this.oauthProvider = oauthProvider
+	}
+
+	async listCalendarIds(): Promise<string[]> {
+		const url = `${DefaultGoogleCalendarClient.API_BASE}/users/me/calendarList?fields=items(id)`
+		const json = await this.request(url)
+		const result = calendarListResponseSchema(json)
+
+		if (result instanceof type.errors) {
+			throw new Error(`Google Calendar API response validation failed: ${result.summary}`)
+		}
+
+		if (!result.items) {
+			return []
+		}
+		return result.items.map((entry) => entry.id)
+	}
+
+	async listEvents(options: ListEventsOptions): Promise<ApiCalendarEvent[]> {
+		const url = new URL(
+			`${DefaultGoogleCalendarClient.API_BASE}/calendars/${encodeURIComponent(options.calendarId)}/events`,
+		)
+		url.searchParams.set("timeMin", options.timeMin.toISOString())
+		url.searchParams.set("timeMax", options.timeMax.toISOString())
+		url.searchParams.set("singleEvents", "true")
+		url.searchParams.set("orderBy", "startTime")
+
+		const json = await this.request(url.toString())
+		const result = eventsResponseSchema(json)
+
+		if (result instanceof type.errors) {
+			throw new Error(`Google Calendar API response validation failed: ${result.summary}`)
+		}
+
+		if (!result.items) {
+			return []
+		}
+
+		return result.items
+	}
+
+	/** Authenticated GET with auto token refresh on 401. */
+	private async request(url: string): Promise<unknown> {
+		const token = await this.oauthProvider.fetchAccessToken()
+		let response = await fetch(url, {
+			headers: { Authorization: `Bearer ${token}` },
+		})
+
+		if (response.status === 401) {
+			const newToken = await this.oauthProvider.refresh()
+			response = await fetch(url, {
+				headers: { Authorization: `Bearer ${newToken}` },
+			})
+		}
+
+		if (!response.ok) {
+			const body = await response.text()
+			throw new Error(
+				`Google Calendar API error: ${response.status} ${response.statusText}: ${body}`,
+			)
+		}
+
+		return response.json()
+	}
+}
--- a/packages/aris-source-google-calendar/src/google-calendar-source.test.ts
+++ b/packages/aris-source-google-calendar/src/google-calendar-source.test.ts
@@ -0,0 +1,296 @@
+import { contextValue, type Context } from "@aris/core"
+import { describe, expect, test } from "bun:test"
+
+import type { ApiCalendarEvent, GoogleCalendarClient, ListEventsOptions } from "./types"
+
+import fixture from "../fixtures/events.json"
+import { NextEventKey } from "./calendar-context"
+import { CalendarFeedItemType } from "./feed-items"
+import { GoogleCalendarSource } from "./google-calendar-source"
+
+const NOW = new Date("2026-01-20T10:00:00Z")
+
+function fixtureEvents(): ApiCalendarEvent[] {
+	return fixture.items as unknown as ApiCalendarEvent[]
+}
+
+function createMockClient(
+	eventsByCalendar: Record<string, ApiCalendarEvent[]>,
+): GoogleCalendarClient {
+	return {
+		listCalendarIds: async () => Object.keys(eventsByCalendar),
+		listEvents: async (options: ListEventsOptions) => {
+			const events = eventsByCalendar[options.calendarId] ?? []
+			return events.filter((e) => {
+				const startRaw = e.start.dateTime ?? e.start.date ?? ""
+				const endRaw = e.end.dateTime ?? e.end.date ?? ""
+				return (
+					new Date(startRaw).getTime() < options.timeMax.getTime() &&
+					new Date(endRaw).getTime() > options.timeMin.getTime()
+				)
+			})
+		},
+	}
+}
+
+function defaultMockClient(): GoogleCalendarClient {
+	return createMockClient({ primary: fixtureEvents() })
+}
+
+function createContext(time?: Date): Context {
+	return { time: time ?? NOW }
+}
+
+describe("GoogleCalendarSource", () => {
+	describe("constructor", () => {
+		test("has correct id", () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			expect(source.id).toBe("aris.google-calendar")
+		})
+	})
+
+	describe("fetchItems", () => {
+		test("returns empty array when no events", async () => {
+			const source = new GoogleCalendarSource({
+				client: createMockClient({ primary: [] }),
+			})
+			const items = await source.fetchItems(createContext())
+			expect(items).toEqual([])
+		})
+
+		test("returns feed items for all events in window", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			expect(items.length).toBe(fixture.items.length)
+		})
+
+		test("assigns calendar-event type to timed events", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			const timedItems = items.filter((i) => i.type === CalendarFeedItemType.event)
+			expect(timedItems.length).toBe(4)
+		})
+
+		test("assigns calendar-all-day type to all-day events", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			const allDayItems = items.filter((i) => i.type === CalendarFeedItemType.allDay)
+			expect(allDayItems.length).toBe(1)
+		})
+
+		test("ongoing events get highest priority (1.0)", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			const ongoing = items.find((i) => i.data.eventId === "evt-ongoing")
+			expect(ongoing).toBeDefined()
+			expect(ongoing!.priority).toBe(1.0)
+		})
+
+		test("upcoming events get higher priority when sooner", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			const soon = items.find((i) => i.data.eventId === "evt-soon")
+			const later = items.find((i) => i.data.eventId === "evt-later")
+
+			expect(soon).toBeDefined()
+			expect(later).toBeDefined()
+			expect(soon!.priority).toBeGreaterThan(later!.priority)
+		})
+
+		test("all-day events get flat priority (0.4)", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			const allDay = items.find((i) => i.data.eventId === "evt-allday")
+			expect(allDay).toBeDefined()
+			expect(allDay!.priority).toBe(0.4)
+		})
+
+		test("generates unique IDs for each item", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			const ids = items.map((i) => i.id)
+			const uniqueIds = new Set(ids)
+			expect(uniqueIds.size).toBe(ids.length)
+		})
+
+		test("sets timestamp from context.time", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			for (const item of items) {
+				expect(item.timestamp).toEqual(NOW)
+			}
+		})
+
+		test("respects lookaheadHours", async () => {
+			// Only 2 hours lookahead from 10:00 → events before 12:00
+			const source = new GoogleCalendarSource({
+				client: defaultMockClient(),
+				lookaheadHours: 2,
+			})
+			const items = await source.fetchItems(createContext())
+
+			// Should include: ongoing (09:30-10:15), soon (10:10-10:40), allday (00:00-next day)
+			// Should exclude: later (14:00), tentative lunch (12:00)
+			const eventIds = items.map((i) => i.data.eventId)
+			expect(eventIds).toContain("evt-ongoing")
+			expect(eventIds).toContain("evt-soon")
+			expect(eventIds).toContain("evt-allday")
+			expect(eventIds).not.toContain("evt-later")
+			expect(eventIds).not.toContain("evt-tentative")
+		})
+
+		test("defaults to all user calendars via listCalendarIds", async () => {
+			const workEvent: ApiCalendarEvent = {
+				id: "evt-work",
+				status: "confirmed",
+				htmlLink: "https://calendar.google.com/event?eid=evt-work",
+				summary: "Work Meeting",
+				start: { dateTime: "2026-01-20T11:00:00Z" },
+				end: { dateTime: "2026-01-20T12:00:00Z" },
+			}
+
+			const client = createMockClient({
+				primary: fixtureEvents(),
+				"work@example.com": [workEvent],
+			})
+
+			// No calendarIds provided — should discover both calendars
+			const source = new GoogleCalendarSource({ client })
+			const items = await source.fetchItems(createContext())
+
+			const eventIds = items.map((i) => i.data.eventId)
+			expect(eventIds).toContain("evt-work")
+			expect(eventIds).toContain("evt-ongoing")
+		})
+
+		test("fetches from explicit calendar IDs", async () => {
+			const workEvent: ApiCalendarEvent = {
+				id: "evt-work",
+				status: "confirmed",
+				htmlLink: "https://calendar.google.com/event?eid=evt-work",
+				summary: "Work Meeting",
+				start: { dateTime: "2026-01-20T11:00:00Z" },
+				end: { dateTime: "2026-01-20T12:00:00Z" },
+			}
+
+			const client = createMockClient({
+				primary: fixtureEvents(),
+				"work@example.com": [workEvent],
+			})
+
+			const source = new GoogleCalendarSource({
+				client,
+				calendarIds: ["primary", "work@example.com"],
+			})
+			const items = await source.fetchItems(createContext())
+
+			const eventIds = items.map((i) => i.data.eventId)
+			expect(eventIds).toContain("evt-work")
+			expect(eventIds).toContain("evt-ongoing")
+		})
+	})
+
+	describe("fetchContext", () => {
+		test("returns null when no events", async () => {
+			const source = new GoogleCalendarSource({
+				client: createMockClient({ primary: [] }),
+			})
+			const result = await source.fetchContext(createContext())
+			expect(result).toBeNull()
+		})
+
+		test("returns null when only all-day events", async () => {
+			const allDayOnly: ApiCalendarEvent[] = [
+				{
+					id: "evt-allday",
+					status: "confirmed",
+					htmlLink: "https://calendar.google.com/event?eid=evt-allday",
+					summary: "Holiday",
+					start: { date: "2026-01-20" },
+					end: { date: "2026-01-21" },
+				},
+			]
+			const source = new GoogleCalendarSource({
+				client: createMockClient({ primary: allDayOnly }),
+			})
+			const result = await source.fetchContext(createContext())
+			expect(result).toBeNull()
+		})
+
+		test("returns next upcoming timed event (not ongoing)", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const result = await source.fetchContext(createContext())
+
+			expect(result).not.toBeNull()
+			const nextEvent = contextValue(result! as Context, NextEventKey)
+			expect(nextEvent).toBeDefined()
+			// evt-soon starts at 10:10, which is the nearest future timed event
+			expect(nextEvent!.title).toBe("1:1 with Manager")
+			expect(nextEvent!.minutesUntilStart).toBe(10)
+			expect(nextEvent!.location).toBeNull()
+		})
+
+		test("includes location when available", async () => {
+			const events: ApiCalendarEvent[] = [
+				{
+					id: "evt-loc",
+					status: "confirmed",
+					htmlLink: "https://calendar.google.com/event?eid=evt-loc",
+					summary: "Offsite",
+					location: "123 Main St",
+					start: { dateTime: "2026-01-20T11:00:00Z" },
+					end: { dateTime: "2026-01-20T12:00:00Z" },
+				},
+			]
+			const source = new GoogleCalendarSource({
+				client: createMockClient({ primary: events }),
+			})
+			const result = await source.fetchContext(createContext())
+
+			expect(result).not.toBeNull()
+			const nextEvent = contextValue(result! as Context, NextEventKey)
+			expect(nextEvent).toBeDefined()
+			expect(nextEvent!.location).toBe("123 Main St")
+		})
+
+		test("skips ongoing events for next-event context", async () => {
+			const events: ApiCalendarEvent[] = [
+				{
+					id: "evt-now",
+					status: "confirmed",
+					htmlLink: "https://calendar.google.com/event?eid=evt-now",
+					summary: "Current Meeting",
+					start: { dateTime: "2026-01-20T09:30:00Z" },
+					end: { dateTime: "2026-01-20T10:30:00Z" },
+				},
+			]
+			const source = new GoogleCalendarSource({
+				client: createMockClient({ primary: events }),
+			})
+			const result = await source.fetchContext(createContext())
+			expect(result).toBeNull()
+		})
+	})
+
+	describe("priority ordering", () => {
+		test("ongoing > upcoming > all-day", async () => {
+			const source = new GoogleCalendarSource({ client: defaultMockClient() })
+			const items = await source.fetchItems(createContext())
+
+			const ongoing = items.find((i) => i.data.eventId === "evt-ongoing")!
+			const upcoming = items.find((i) => i.data.eventId === "evt-soon")!
+			const allDay = items.find((i) => i.data.eventId === "evt-allday")!
+
+			expect(ongoing.priority).toBeGreaterThan(upcoming.priority)
+			expect(upcoming.priority).toBeGreaterThan(allDay.priority)
+		})
+	})
+})
--- a/packages/aris-source-google-calendar/src/google-calendar-source.ts
+++ b/packages/aris-source-google-calendar/src/google-calendar-source.ts
@@ -0,0 +1,212 @@
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+
+import { UnknownActionError } from "@aris/core"
+
+import type {
+	ApiCalendarEvent,
+	CalendarEventData,
+	GoogleCalendarClient,
+	GoogleOAuthProvider,
+} from "./types"
+
+import { NextEventKey, type NextEvent } from "./calendar-context"
+
+interface GoogleCalendarSourceBaseOptions {
+	calendarIds?: string[]
+	/** Default: 24 */
+	lookaheadHours?: number
+}
+
+interface GoogleCalendarSourceWithProvider extends GoogleCalendarSourceBaseOptions {
+	oauthProvider: GoogleOAuthProvider
+	client?: never
+}
+
+interface GoogleCalendarSourceWithClient extends GoogleCalendarSourceBaseOptions {
+	oauthProvider?: never
+	client: GoogleCalendarClient
+}
+
+export type GoogleCalendarSourceOptions =
+	| GoogleCalendarSourceWithProvider
+	| GoogleCalendarSourceWithClient
+import { CalendarFeedItemType, type CalendarFeedItem } from "./feed-items"
+import { DefaultGoogleCalendarClient } from "./google-calendar-api"
+
+const DEFAULT_LOOKAHEAD_HOURS = 24
+
+const PRIORITY_ONGOING = 1.0
+const PRIORITY_UPCOMING_MAX = 0.9
+const PRIORITY_UPCOMING_MIN = 0.3
+const PRIORITY_ALL_DAY = 0.4
+
+/**
+ * A FeedSource that provides Google Calendar events and next-event context.
+ *
+ * Fetches upcoming and all-day events within a configurable lookahead window.
+ * Provides a NextEvent context for downstream sources to react to the user's schedule.
+ *
+ * @example
+ * ```ts
+ * const calendarSource = new GoogleCalendarSource({
+ *   oauthProvider: myOAuthProvider,
+ *   calendarIds: ["primary", "work@example.com"],
+ *   lookaheadHours: 12,
+ * })
+ *
+ * const engine = new FeedEngine()
+ *   .register(calendarSource)
+ *
+ * // Access next-event context in downstream sources
+ * const next = contextValue(context, NextEventKey)
+ * if (next && next.minutesUntilStart < 15) {
+ *   // remind user
+ * }
+ * ```
+ */
+export class GoogleCalendarSource implements FeedSource<CalendarFeedItem> {
+	readonly id = "aris.google-calendar"
+
+	private readonly client: GoogleCalendarClient
+	private readonly calendarIds: string[] | undefined
+	private readonly lookaheadHours: number
+
+	constructor(options: GoogleCalendarSourceOptions) {
+		this.client = options.client ?? new DefaultGoogleCalendarClient(options.oauthProvider)
+		this.calendarIds = options.calendarIds
+		this.lookaheadHours = options.lookaheadHours ?? DEFAULT_LOOKAHEAD_HOURS
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	}
+
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	}
+
+	async fetchContext(context: Context): Promise<Partial<Context> | null> {
+		const events = await this.fetchAllEvents(context.time)
+
+		const now = context.time.getTime()
+		const nextTimedEvent = events.find((e) => !e.isAllDay && e.startTime.getTime() > now)
+
+		if (!nextTimedEvent) {
+			return null
+		}
+
+		const minutesUntilStart = (nextTimedEvent.startTime.getTime() - now) / 60_000
+
+		const nextEvent: NextEvent = {
+			title: nextTimedEvent.title,
+			startTime: nextTimedEvent.startTime,
+			endTime: nextTimedEvent.endTime,
+			minutesUntilStart,
+			location: nextTimedEvent.location,
+		}
+
+		return { [NextEventKey]: nextEvent }
+	}
+
+	async fetchItems(context: Context): Promise<CalendarFeedItem[]> {
+		const events = await this.fetchAllEvents(context.time)
+		const now = context.time.getTime()
+		const lookaheadMs = this.lookaheadHours * 60 * 60 * 1000
+
+		return events.map((event) => createFeedItem(event, now, lookaheadMs))
+	}
+
+	private async resolveCalendarIds(): Promise<string[]> {
+		if (this.calendarIds) {
+			return this.calendarIds
+		}
+		return this.client.listCalendarIds()
+	}
+
+	private async fetchAllEvents(time: Date): Promise<CalendarEventData[]> {
+		const timeMax = new Date(time.getTime() + this.lookaheadHours * 60 * 60 * 1000)
+		const calendarIds = await this.resolveCalendarIds()
+
+		const results = await Promise.all(
+			calendarIds.map(async (calendarId) => {
+				const raw = await this.client.listEvents({
+					calendarId,
+					timeMin: time,
+					timeMax,
+				})
+				return raw.map((event) => parseEvent(event, calendarId))
+			}),
+		)
+
+		const allEvents = results.flat()
+
+		// Sort by start time ascending
+		allEvents.sort((a, b) => a.startTime.getTime() - b.startTime.getTime())
+
+		return allEvents
+	}
+}
+
+function parseEvent(event: ApiCalendarEvent, calendarId: string): CalendarEventData {
+	const startRaw = event.start.dateTime ?? event.start.date
+	const endRaw = event.end.dateTime ?? event.end.date
+
+	if (!startRaw || !endRaw) {
+		throw new Error(`Event ${event.id} is missing start or end date`)
+	}
+
+	const isAllDay = !event.start.dateTime
+
+	return {
+		eventId: event.id,
+		calendarId,
+		title: event.summary ?? "(No title)",
+		description: event.description ?? null,
+		location: event.location ?? null,
+		startTime: new Date(startRaw),
+		endTime: new Date(endRaw),
+		isAllDay,
+		status: event.status,
+		htmlLink: event.htmlLink,
+	}
+}
+
+function computePriority(event: CalendarEventData, nowMs: number, lookaheadMs: number): number {
+	if (event.isAllDay) {
+		return PRIORITY_ALL_DAY
+	}
+
+	const startMs = event.startTime.getTime()
+	const endMs = event.endTime.getTime()
+
+	// Ongoing: start <= now < end
+	if (startMs <= nowMs && nowMs < endMs) {
+		return PRIORITY_ONGOING
+	}
+
+	// Upcoming: linear decay from PRIORITY_UPCOMING_MAX to PRIORITY_UPCOMING_MIN
+	const msUntilStart = startMs - nowMs
+	if (msUntilStart <= 0) {
+		return PRIORITY_UPCOMING_MIN
+	}
+
+	const ratio = Math.min(msUntilStart / lookaheadMs, 1)
+	return PRIORITY_UPCOMING_MAX - ratio * (PRIORITY_UPCOMING_MAX - PRIORITY_UPCOMING_MIN)
+}
+
+function createFeedItem(
+	event: CalendarEventData,
+	nowMs: number,
+	lookaheadMs: number,
+): CalendarFeedItem {
+	const priority = computePriority(event, nowMs, lookaheadMs)
+	const itemType = event.isAllDay ? CalendarFeedItemType.allDay : CalendarFeedItemType.event
+
+	return {
+		id: `calendar-${event.calendarId}-${event.eventId}`,
+		type: itemType,
+		priority,
+		timestamp: new Date(nowMs),
+		data: event,
+	}
+}
--- a/packages/aris-source-google-calendar/src/index.ts
+++ b/packages/aris-source-google-calendar/src/index.ts
@@ -0,0 +1,20 @@
+export { NextEventKey, type NextEvent } from "./calendar-context"
+export {
+	CalendarFeedItemType,
+	type CalendarFeedItemType as CalendarFeedItemTypeType,
+	type CalendarAllDayFeedItem,
+	type CalendarEventFeedItem,
+	type CalendarFeedItem,
+} from "./feed-items"
+export { DefaultGoogleCalendarClient } from "./google-calendar-api"
+export { GoogleCalendarSource, type GoogleCalendarSourceOptions } from "./google-calendar-source"
+export {
+	EventStatus,
+	type EventStatus as EventStatusType,
+	type ApiCalendarEvent,
+	type ApiEventDateTime,
+	type CalendarEventData,
+	type GoogleCalendarClient,
+	type GoogleOAuthProvider,
+	type ListEventsOptions,
+} from "./types"
--- a/packages/aris-source-google-calendar/src/types.ts
+++ b/packages/aris-source-google-calendar/src/types.ts
@@ -0,0 +1,55 @@
+export interface GoogleOAuthProvider {
+	fetchAccessToken(): Promise<string>
+	refresh(): Promise<string>
+	revoke(): Promise<void>
+}
+
+export const EventStatus = {
+	Confirmed: "confirmed",
+	Tentative: "tentative",
+	Cancelled: "cancelled",
+} as const
+
+export type EventStatus = (typeof EventStatus)[keyof typeof EventStatus]
+
+/** Exactly one of dateTime or date is present. */
+export interface ApiEventDateTime {
+	dateTime?: string
+	date?: string
+	timeZone?: string
+}
+
+export interface ApiCalendarEvent {
+	id: string
+	status: EventStatus
+	htmlLink: string
+	summary?: string
+	description?: string
+	location?: string
+	start: ApiEventDateTime
+	end: ApiEventDateTime
+}
+
+export type CalendarEventData = {
+	eventId: string
+	calendarId: string
+	title: string
+	description: string | null
+	location: string | null
+	startTime: Date
+	endTime: Date
+	isAllDay: boolean
+	status: EventStatus
+	htmlLink: string
+}
+
+export interface ListEventsOptions {
+	calendarId: string
+	timeMin: Date
+	timeMax: Date
+}
+
+export interface GoogleCalendarClient {
+	listCalendarIds(): Promise<string[]>
+	listEvents(options: ListEventsOptions): Promise<ApiCalendarEvent[]>
+}
--- a/packages/aris-source-location/package.json
+++ b/packages/aris-source-location/package.json
@@ -8,6 +8,7 @@
 		"test": "bun test src/"
 	},
 	"dependencies": {
-		"@aris/core": "workspace:*"
+		"@aris/core": "workspace:*",
+		"arktype": "^2.1.0"
 	}
 }
--- a/packages/aris-source-location/src/index.ts
+++ b/packages/aris-source-location/src/index.ts
@@ -1,6 +1,2 @@
-export {
-	LocationSource,
-	LocationKey,
-	type Location,
-	type LocationSourceOptions,
-} from "./location-source.ts"
+export { LocationSource, LocationKey } from "./location-source.ts"
+export { Location, type LocationSourceOptions } from "./types.ts"
--- a/packages/aris-source-location/src/location-source.test.ts
+++ b/packages/aris-source-location/src/location-source.test.ts
@@ -16,7 +16,7 @@ describe("LocationSource", () => {
 	describe("FeedSource interface", () => {
 		test("has correct id", () => {
 			const source = new LocationSource()
-			expect(source.id).toBe("location")
+			expect(source.id).toBe("aris.location")
 		})

 		test("fetchItems always returns empty array", async () => {
@@ -27,11 +27,11 @@ describe("LocationSource", () => {
 			expect(items).toEqual([])
 		})

-		test("fetchContext returns empty when no location", async () => {
+		test("fetchContext returns null when no location", async () => {
 			const source = new LocationSource()

 			const context = await source.fetchContext()
-			expect(context).toEqual({})
+			expect(context).toBeNull()
 		})

 		test("fetchContext returns location when available", async () => {
@@ -147,4 +147,40 @@ describe("LocationSource", () => {
 			expect(listener2).toHaveBeenCalledTimes(1)
 		})
 	})
+
+	describe("actions", () => {
+		test("listActions returns update-location action", async () => {
+			const source = new LocationSource()
+			const actions = await source.listActions()
+
+			expect(actions["update-location"]).toBeDefined()
+			expect(actions["update-location"]!.id).toBe("update-location")
+			expect(actions["update-location"]!.input).toBeDefined()
+		})
+
+		test("executeAction update-location pushes location", async () => {
+			const source = new LocationSource()
+
+			expect(source.lastLocation).toBeNull()
+
+			const location = createLocation({ lat: 40.7128, lng: -74.006 })
+			await source.executeAction("update-location", location)
+
+			expect(source.lastLocation).toEqual(location)
+		})
+
+		test("executeAction throws on invalid input", async () => {
+			const source = new LocationSource()
+
+			await expect(
+				source.executeAction("update-location", { lat: "not a number" }),
+			).rejects.toThrow()
+		})
+
+		test("executeAction throws for unknown action", async () => {
+			const source = new LocationSource()
+
+			await expect(source.executeAction("nonexistent", {})).rejects.toThrow("Unknown action")
+		})
+	})
 })
--- a/packages/aris-source-location/src/location-source.ts
+++ b/packages/aris-source-location/src/location-source.ts
@@ -1,22 +1,9 @@
-import type { Context, FeedSource } from "@aris/core"
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"

-import { contextKey, type ContextKey } from "@aris/core"
+import { UnknownActionError, contextKey, type ContextKey } from "@aris/core"
+import { type } from "arktype"

-/**
- * Geographic coordinates with accuracy and timestamp.
- */
-export interface Location {
-	lat: number
-	lng: number
-	/** Accuracy in meters */
-	accuracy: number
-	timestamp: Date
-}
-
-export interface LocationSourceOptions {
-	/** Number of locations to retain in history. Defaults to 1. */
-	historySize?: number
-}
+import { Location, type LocationSourceOptions } from "./types.ts"

 export const LocationKey: ContextKey<Location> = contextKey("location")

@@ -29,7 +16,7 @@ export const LocationKey: ContextKey<Location> = contextKey("location")
 * Does not produce feed items - always returns empty array from `fetchItems`.
 */
 export class LocationSource implements FeedSource {
-	readonly id = "location"
+	readonly id = "aris.location"

 	private readonly historySize: number
 	private locations: Location[] = []
@@ -39,6 +26,31 @@ export class LocationSource implements FeedSource {
 		this.historySize = options.historySize ?? 1
 	}

+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {
+			"update-location": {
+				id: "update-location",
+				description: "Push a new location update",
+				input: Location,
+			},
+		}
+	}
+
+	async executeAction(actionId: string, params: unknown): Promise<void> {
+		switch (actionId) {
+			case "update-location": {
+				const result = Location(params)
+				if (result instanceof type.errors) {
+					throw new Error(result.summary)
+				}
+				this.pushLocation(result)
+				return
+			}
+			default:
+				throw new UnknownActionError(actionId)
+		}
+	}
+
 	/**
 	 * Push a new location update. Notifies all context listeners.
 	 */
@@ -73,11 +85,11 @@ export class LocationSource implements FeedSource {
 		}
 	}

-	async fetchContext(): Promise<Partial<Context>> {
+	async fetchContext(): Promise<Partial<Context> | null> {
 		if (this.lastLocation) {
 			return { [LocationKey]: this.lastLocation }
 		}
-		return {}
+		return null
 	}

 	async fetchItems(): Promise<[]> {
--- a/packages/aris-source-location/src/types.ts
+++ b/packages/aris-source-location/src/types.ts
@@ -0,0 +1,17 @@
+import { type } from "arktype"
+
+/** Geographic coordinates with accuracy and timestamp. */
+export const Location = type({
+	lat: "number",
+	lng: "number",
+	/** Accuracy in meters */
+	accuracy: "number",
+	timestamp: "Date",
+})
+
+export type Location = typeof Location.infer
+
+export interface LocationSourceOptions {
+	/** Number of locations to retain in history. Defaults to 1. */
+	historySize?: number
+}
--- a/packages/aris-source-tfl/src/index.ts
+++ b/packages/aris-source-tfl/src/index.ts
@@ -2,6 +2,7 @@ export { TflSource } from "./tfl-source.ts"
 export { TflApi } from "./tfl-api.ts"
 export type { TflLineId } from "./tfl-api.ts"
 export type {
+	ITflApi,
 	StationLocation,
 	TflAlertData,
 	TflAlertFeedItem,
--- a/packages/aris-source-tfl/src/tfl-api.ts
+++ b/packages/aris-source-tfl/src/tfl-api.ts
@@ -142,7 +142,7 @@ export class TflApi {

 // Schemas

-const lineId = type(
+export const lineId = type(
 	"'bakerloo' | 'central' | 'circle' | 'district' | 'hammersmith-city' | 'jubilee' | 'metropolitan' | 'northern' | 'piccadilly' | 'victoria' | 'waterloo-city' | 'lioness' | 'mildmay' | 'windrush' | 'weaver' | 'suffragette' | 'liberty' | 'elizabeth'",
 )

--- a/packages/aris-source-tfl/src/tfl-source.test.ts
+++ b/packages/aris-source-tfl/src/tfl-source.test.ts
@@ -94,12 +94,12 @@ describe("TflSource", () => {
 	describe("interface", () => {
 		test("has correct id", () => {
 			const source = new TflSource({ client: api })
-			expect(source.id).toBe("tfl")
+			expect(source.id).toBe("aris.tfl")
 		})

 		test("depends on location", () => {
 			const source = new TflSource({ client: api })
-			expect(source.dependencies).toEqual(["location"])
+			expect(source.dependencies).toEqual(["aris.location"])
 		})

 		test("implements fetchItems", () => {
@@ -112,6 +112,57 @@ describe("TflSource", () => {
 		})
 	})

+	describe("setLinesOfInterest", () => {
+		const lineFilteringApi: ITflApi = {
+			async fetchLineStatuses(lines?: TflLineId[]): Promise<TflLineStatus[]> {
+				const all: TflLineStatus[] = [
+					{
+						lineId: "northern",
+						lineName: "Northern",
+						severity: "minor-delays",
+						description: "Delays",
+					},
+					{
+						lineId: "central",
+						lineName: "Central",
+						severity: "closure",
+						description: "Closed",
+					},
+				]
+				return lines ? all.filter((s) => lines.includes(s.lineId)) : all
+			},
+			async fetchStations(): Promise<StationLocation[]> {
+				return []
+			},
+		}
+
+		test("changes which lines are fetched", async () => {
+			const source = new TflSource({ client: lineFilteringApi })
+			const before = await source.fetchItems(createContext())
+			expect(before.length).toBe(2)
+
+			source.setLinesOfInterest(["northern"])
+			const after = await source.fetchItems(createContext())
+
+			expect(after.length).toBe(1)
+			expect(after[0]!.data.line).toBe("northern")
+		})
+
+		test("DEFAULT_LINES_OF_INTEREST restores all lines", async () => {
+			const source = new TflSource({
+				client: lineFilteringApi,
+				lines: ["northern"],
+			})
+			const filtered = await source.fetchItems(createContext())
+			expect(filtered.length).toBe(1)
+
+			source.setLinesOfInterest([...TflSource.DEFAULT_LINES_OF_INTEREST])
+			const all = await source.fetchItems(createContext())
+
+			expect(all.length).toBe(2)
+		})
+	})
+
 	describe("fetchItems", () => {
 		test("returns feed items array", async () => {
 			const source = new TflSource({ client: api })
@@ -121,7 +172,12 @@ describe("TflSource", () => {

 		test("feed items have correct base structure", async () => {
 			const source = new TflSource({ client: api })
-			const location: Location = { lat: 51.5074, lng: -0.1278, accuracy: 10, timestamp: new Date() }
+			const location: Location = {
+				lat: 51.5074,
+				lng: -0.1278,
+				accuracy: 10,
+				timestamp: new Date(),
+			}
 			const items = await source.fetchItems(createContext(location))

 			for (const item of items) {
@@ -135,7 +191,12 @@ describe("TflSource", () => {

 		test("feed items have correct data structure", async () => {
 			const source = new TflSource({ client: api })
-			const location: Location = { lat: 51.5074, lng: -0.1278, accuracy: 10, timestamp: new Date() }
+			const location: Location = {
+				lat: 51.5074,
+				lng: -0.1278,
+				accuracy: 10,
+				timestamp: new Date(),
+			}
 			const items = await source.fetchItems(createContext(location))

 			for (const item of items) {
@@ -187,7 +248,12 @@ describe("TflSource", () => {

 		test("closestStationDistance is number when location provided", async () => {
 			const source = new TflSource({ client: api })
-			const location: Location = { lat: 51.5074, lng: -0.1278, accuracy: 10, timestamp: new Date() }
+			const location: Location = {
+				lat: 51.5074,
+				lng: -0.1278,
+				accuracy: 10,
+				timestamp: new Date(),
+			}
 			const items = await source.fetchItems(createContext(location))

 			for (const item of items) {
@@ -205,6 +271,62 @@ describe("TflSource", () => {
 			}
 		})
 	})
+
+	describe("actions", () => {
+		test("listActions returns set-lines-of-interest", async () => {
+			const source = new TflSource({ client: api })
+			const actions = await source.listActions()
+
+			expect(actions["set-lines-of-interest"]).toBeDefined()
+			expect(actions["set-lines-of-interest"]!.id).toBe("set-lines-of-interest")
+		})
+
+		test("executeAction set-lines-of-interest updates lines", async () => {
+			const lineFilteringApi: ITflApi = {
+				async fetchLineStatuses(lines?: TflLineId[]): Promise<TflLineStatus[]> {
+					const all: TflLineStatus[] = [
+						{
+							lineId: "northern",
+							lineName: "Northern",
+							severity: "minor-delays",
+							description: "Delays",
+						},
+						{
+							lineId: "central",
+							lineName: "Central",
+							severity: "closure",
+							description: "Closed",
+						},
+					]
+					return lines ? all.filter((s) => lines.includes(s.lineId)) : all
+				},
+				async fetchStations(): Promise<StationLocation[]> {
+					return []
+				},
+			}
+
+			const source = new TflSource({ client: lineFilteringApi })
+			await source.executeAction("set-lines-of-interest", ["northern"])
+
+			const items = await source.fetchItems(createContext())
+			expect(items.length).toBe(1)
+			expect(items[0]!.data.line).toBe("northern")
+		})
+
+		test("executeAction throws on invalid input", async () => {
+			const source = new TflSource({ client: api })
+
+			await expect(
+				source.executeAction("set-lines-of-interest", "not-an-array"),
+			).rejects.toThrow()
+		})
+
+		test("executeAction throws for unknown action", async () => {
+			const source = new TflSource({ client: api })
+
+			await expect(source.executeAction("nonexistent", {})).rejects.toThrow("Unknown action")
+		})
+	})
 })

 describe("TfL Fixture Data Shape", () => {
--- a/packages/aris-source-tfl/src/tfl-source.ts
+++ b/packages/aris-source-tfl/src/tfl-source.ts
@@ -1,7 +1,8 @@
-import type { Context, FeedSource } from "@aris/core"
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"

-import { contextValue } from "@aris/core"
+import { UnknownActionError, contextValue } from "@aris/core"
 import { LocationKey } from "@aris/source-location"
+import { type } from "arktype"

 import type {
 	ITflApi,
@@ -13,7 +14,9 @@ import type {
 	TflSourceOptions,
 } from "./types.ts"

-import { TflApi } from "./tfl-api.ts"
+import { TflApi, lineId } from "./tfl-api.ts"
+
+const setLinesInput = lineId.array()

 const SEVERITY_PRIORITY: Record<TflAlertSeverity, number> = {
 	closure: 1.0,
@@ -42,18 +45,75 @@ const SEVERITY_PRIORITY: Record<TflAlertSeverity, number> = {
 * ```
 */
 export class TflSource implements FeedSource<TflAlertFeedItem> {
-	readonly id = "tfl"
-	readonly dependencies = ["location"]
+	static readonly DEFAULT_LINES_OF_INTEREST: readonly TflLineId[] = [
+		"bakerloo",
+		"central",
+		"circle",
+		"district",
+		"hammersmith-city",
+		"jubilee",
+		"metropolitan",
+		"northern",
+		"piccadilly",
+		"victoria",
+		"waterloo-city",
+		"lioness",
+		"mildmay",
+		"windrush",
+		"weaver",
+		"suffragette",
+		"liberty",
+		"elizabeth",
+	]
+
+	readonly id = "aris.tfl"
+	readonly dependencies = ["aris.location"]

 	private readonly client: ITflApi
-	private readonly lines?: TflLineId[]
+	private lines: TflLineId[]

 	constructor(options: TflSourceOptions) {
 		if (!options.client && !options.apiKey) {
 			throw new Error("Either client or apiKey must be provided")
 		}
 		this.client = options.client ?? new TflApi(options.apiKey!)
-		this.lines = options.lines
+		this.lines = options.lines ?? [...TflSource.DEFAULT_LINES_OF_INTEREST]
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {
+			"set-lines-of-interest": {
+				id: "set-lines-of-interest",
+				description: "Update the set of monitored TfL lines",
+				input: setLinesInput,
+			},
+		}
+	}
+
+	async executeAction(actionId: string, params: unknown): Promise<void> {
+		switch (actionId) {
+			case "set-lines-of-interest": {
+				const result = setLinesInput(params)
+				if (result instanceof type.errors) {
+					throw new Error(result.summary)
+				}
+				this.setLinesOfInterest(result)
+				return
+			}
+			default:
+				throw new UnknownActionError(actionId)
+		}
+	}
+
+	async fetchContext(): Promise<null> {
+		return null
+	}
+
+	/**
+	 * Update the set of monitored lines. Takes effect on the next fetchItems call.
+	 */
+	setLinesOfInterest(lines: TflLineId[]): void {
+		this.lines = lines
 	}

 	async fetchItems(context: Context): Promise<TflAlertFeedItem[]> {
--- a/packages/aris-source-weatherkit/src/weather-source.test.ts
+++ b/packages/aris-source-weatherkit/src/weather-source.test.ts
@@ -34,12 +34,12 @@ describe("WeatherSource", () => {
 	describe("properties", () => {
 		test("has correct id", () => {
 			const source = new WeatherSource({ credentials: mockCredentials })
-			expect(source.id).toBe("weather")
+			expect(source.id).toBe("aris.weather")
 		})

 		test("depends on location", () => {
 			const source = new WeatherSource({ credentials: mockCredentials })
-			expect(source.dependencies).toEqual(["location"])
+			expect(source.dependencies).toEqual(["aris.location"])
 		})

 		test("throws error if neither client nor credentials provided", () => {
@@ -52,11 +52,11 @@ describe("WeatherSource", () => {
 	describe("fetchContext", () => {
 		const mockClient = createMockClient(fixture.response as WeatherKitResponse)

-		test("returns empty when no location", async () => {
+		test("returns null when no location", async () => {
 			const source = new WeatherSource({ client: mockClient })
 			const result = await source.fetchContext(createMockContext())

-			expect(result).toEqual({})
+			expect(result).toBeNull()
 		})

 		test("returns simplified weather context", async () => {
@@ -64,7 +64,8 @@ describe("WeatherSource", () => {
 			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })

 			const result = await source.fetchContext(context)
-			const weather = contextValue(result, WeatherKey)
+			expect(result).not.toBeNull()
+			const weather = contextValue(result! as Context, WeatherKey)

 			expect(weather).toBeDefined()
 			expect(typeof weather!.temperature).toBe("number")
@@ -77,11 +78,15 @@ describe("WeatherSource", () => {
 		})

 		test("converts temperature to imperial", async () => {
-			const source = new WeatherSource({ client: mockClient, units: Units.imperial })
+			const source = new WeatherSource({
+				client: mockClient,
+				units: Units.imperial,
+			})
 			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })

 			const result = await source.fetchContext(context)
-			const weather = contextValue(result, WeatherKey)
+			expect(result).not.toBeNull()
+			const weather = contextValue(result! as Context, WeatherKey)

 			// Fixture has temperature around 10°C, imperial should be around 50°F
 			expect(weather!.temperature).toBeGreaterThan(40)
--- a/packages/aris-source-weatherkit/src/weather-source.ts
+++ b/packages/aris-source-weatherkit/src/weather-source.ts
@@ -1,6 +1,6 @@
-import type { Context, FeedSource } from "@aris/core"
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"

-import { contextValue } from "@aris/core"
+import { UnknownActionError, contextValue } from "@aris/core"
 import { LocationKey } from "@aris/source-location"

 import { WeatherFeedItemType, type WeatherFeedItem } from "./feed-items"
@@ -93,8 +93,8 @@ const MODERATE_CONDITIONS = new Set<ConditionCode>([
 * ```
 */
 export class WeatherSource implements FeedSource<WeatherFeedItem> {
-	readonly id = "weather"
-	readonly dependencies = ["location"]
+	readonly id = "aris.weather"
+	readonly dependencies = ["aris.location"]

 	private readonly client: WeatherKitClient
 	private readonly hourlyLimit: number
@@ -111,10 +111,18 @@ export class WeatherSource implements FeedSource<WeatherFeedItem> {
 		this.units = options.units ?? Units.metric
 	}

-	async fetchContext(context: Context): Promise<Partial<Context>> {
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	}
+
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	}
+
+	async fetchContext(context: Context): Promise<Partial<Context> | null> {
 		const location = contextValue(context, LocationKey)
 		if (!location) {
-			return {}
+			return null
 		}

 		const response = await this.client.fetch({
@@ -123,7 +131,7 @@ export class WeatherSource implements FeedSource<WeatherFeedItem> {
 		})

 		if (!response.currentWeather) {
-			return {}
+			return null
 		}

 		const weather: Weather = {
Author	SHA1	Message	Date
kenneth	699155e0d8	feat: add actions to FeedSource interface Add listActions() and executeAction() to FeedSource for write operations back to external services. Actions use arktype schemas for input validation via StandardSchemaV1. - ActionDefinition type with optional input schema - FeedEngine routes actions with existence and ID validation - Source IDs use reverse-domain format (aris.location, aris.tfl) - LocationSource: update-location action with schema validation - TflSource: set-lines-of-interest action with lineId validation - No-op implementations for sources without actions Co-authored-by: Ona <no-reply@ona.com>	2026-02-15 12:53:10 +00:00
Kenneth	4d6cac7ec8	Merge pull request #26 from kennethnym/refactor/required-fetch-context refactor: make fetchContext required on FeedSource	2026-02-14 16:41:34 +00:00
kenneth	1f2920a7ad	refactor: make fetchContext required on FeedSource Sources that cannot provide context now return null instead of omitting the method. The engine checks the return value rather than method existence. Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 16:20:24 +00:00
Kenneth	476c6f06d9	Merge pull request #25 from kennethnym/feat/google-calendar-source feat: add Google Calendar data source	2026-02-14 15:44:03 +00:00
kenneth	bfdc5e67b7	chore: restore default comment on lookaheadHours Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 15:43:00 +00:00
kenneth	2cf6536e48	refactor: move source options into source file Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 15:42:59 +00:00
kenneth	c7a1048320	chore: remove obvious comments from types Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 15:42:59 +00:00
kenneth	512faf191e	feat: add Google Calendar data source Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 15:42:59 +00:00
Kenneth	e5d65816dc	Merge pull request #24 from kennethnym/feat/apple-calendar-source feat: add Apple Calendar source package	2026-02-14 15:42:04 +00:00
kenneth	13c411c842	perf: cache fetched events within a refresh cycle FeedEngine calls fetchContext then fetchItems with the same context. Cache events by context.time reference to avoid duplicate CalDAV round-trips. Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 15:36:36 +00:00
kenneth	e8ba49d7bb	refactor: use switch/case in parser, move options - Replace if/else chains with switch/case in ical-parser - Move CalendarSourceOptions to calendar-source.ts Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 15:29:49 +00:00
kenneth	3010eb8990	refactor: replace Map with Record in tests Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 15:20:23 +00:00
kenneth	6c4982ae85	fix: use Promise.allSettled for calendar fetching A transient error on one calendar (e.g. shared calendar with permission issues) no longer discards results from all other calendars. Co-authored-by: Ona <no-reply@ona.com>	2026-02-14 00:44:47 +00:00
kenneth	f557a0f967	feat: add Apple Calendar source package Add @aris/source-apple-calendar for fetching iCloud calendar events via CalDAV using tsdav and ical.js. - CalendarSource implements FeedSource with fetchItems and fetchContext for downstream context - CalendarCredentialProvider interface for token injection - CalendarDAVClient interface for testability - iCal parser extracts full event data including attendees, alarms, organizer, and recurrence - Priority based on event proximity to current time Co-authored-by: Ona <no-reply@ona.com>	2026-02-13 22:08:58 +00:00
Kenneth	1b2929c2b6	Merge pull request #22 from kennethnym/feat/weather-service feat(backend): add WeatherService	2026-02-13 20:05:06 +00:00
Kenneth	c3429e1a77	Merge pull request #23 from kennethnym/feat/tfl-service feat(backend): add TflService	2026-02-13 20:01:03 +00:00
kenneth	54e4b0dcf7	feat(backend): add TflService Manages per-user TflSource instances with individual line configuration. Implements FeedSourceProvider so it can be wired into FeedEngineService. Adds TflSource.setLines() so line config can be mutated in place, keeping engine references valid. Also exports ITflApi from @aris/source-tfl for testability. Co-authored-by: Ona <no-reply@ona.com>	2026-02-13 19:38:21 +00:00