refactor: consolidate backend services

Replace per-source services (LocationService, WeatherService,
TflService, FeedEngineService) with a single UserSessionManager
that owns all per-user state. Source creation is delegated to
thin FeedSourceProvider implementations per source type.

Co-authored-by: Ona <no-reply@ona.com>

.gitignore

@@ -32,3 +32,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+core

apps/aris-backend/src/feed/service.test.ts

@@ -1,162 +0,0 @@
-import { describe, expect, mock, test } from "bun:test"
-
-import { LocationService } from "../location/service.ts"
-import { FeedEngineService } from "./service.ts"
-
-describe("FeedEngineService", () => {
-	test("engineForUser creates engine on first call", () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-
-		const engine = service.engineForUser("user-1")
-
-		expect(engine).toBeDefined()
-	})
-
-	test("engineForUser returns same engine for same user", () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-
-		const engine1 = service.engineForUser("user-1")
-		const engine2 = service.engineForUser("user-1")
-
-		expect(engine1).toBe(engine2)
-	})
-
-	test("engineForUser returns different engines for different users", () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-
-		const engine1 = service.engineForUser("user-1")
-		const engine2 = service.engineForUser("user-2")
-
-		expect(engine1).not.toBe(engine2)
-	})
-
-	test("engineForUser registers sources from all providers", async () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-
-		const engine = service.engineForUser("user-1")
-		const result = await engine.refresh()
-
-		expect(result.errors).toHaveLength(0)
-	})
-
-	test("engineForUser works with empty providers array", async () => {
-		const service = new FeedEngineService([])
-
-		const engine = service.engineForUser("user-1")
-		const result = await engine.refresh()
-
-		expect(result.errors).toHaveLength(0)
-		expect(result.items).toHaveLength(0)
-	})
-
-	test("refresh returns feed result", async () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-
-		const result = await service.refresh("user-1")
-
-		expect(result).toHaveProperty("context")
-		expect(result).toHaveProperty("items")
-		expect(result).toHaveProperty("errors")
-		expect(result.context.time).toBeInstanceOf(Date)
-	})
-
-	test("refresh uses location from LocationService", async () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-		const location = {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		}
-
-		// Create engine first, then update location
-		service.engineForUser("user-1")
-		locationService.updateUserLocation("user-1", location)
-
-		const result = await service.refresh("user-1")
-
-		expect(result.context.location).toEqual(location)
-	})
-
-	test("subscribe receives updates", async () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-		const callback = mock()
-
-		service.subscribe("user-1", callback)
-
-		// Push location to trigger update
-		locationService.updateUserLocation("user-1", {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		})
-
-		// Wait for async update propagation
-		await new Promise((resolve) => setTimeout(resolve, 10))
-
-		expect(callback).toHaveBeenCalled()
-	})
-
-	test("subscribe returns unsubscribe function", async () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-		const callback = mock()
-
-		const unsubscribe = service.subscribe("user-1", callback)
-
-		unsubscribe()
-
-		locationService.updateUserLocation("user-1", {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		})
-
-		await new Promise((resolve) => setTimeout(resolve, 10))
-
-		expect(callback).not.toHaveBeenCalled()
-	})
-
-	test("removeUser stops engine and removes it", async () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-		const callback = mock()
-
-		service.subscribe("user-1", callback)
-
-		service.removeUser("user-1")
-
-		// Push location - should not trigger update since engine is stopped
-		locationService.feedSourceForUser("user-1")
-		locationService.updateUserLocation("user-1", {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		})
-
-		await new Promise((resolve) => setTimeout(resolve, 10))
-
-		expect(callback).not.toHaveBeenCalled()
-	})
-
-	test("removeUser allows new engine to be created", () => {
-		const locationService = new LocationService()
-		const service = new FeedEngineService([locationService])
-
-		const engine1 = service.engineForUser("user-1")
-		service.removeUser("user-1")
-		const engine2 = service.engineForUser("user-1")
-
-		expect(engine1).not.toBe(engine2)
-	})
-})

apps/aris-backend/src/feed/service.ts

@@ -1,75 +0,0 @@
-import { FeedEngine, type FeedResult, type FeedSource, type FeedSubscriber } from "@aris/core"
-
-/**
- * Provides a FeedSource instance for a user.
- */
-export interface FeedSourceProvider {
-	feedSourceForUser(userId: string): FeedSource
-}
-
-/**
- * Manages FeedEngine instances per user.
- *
- * Receives FeedSource instances from injected providers and wires them
- * into per-user engines. Engines are auto-started on creation.
- */
-export class FeedEngineService {
-	private engines = new Map<string, FeedEngine>()
-
-	constructor(private readonly providers: FeedSourceProvider[]) {}
-
-	/**
-	 * Get or create a FeedEngine for a user.
-	 * Automatically registers sources and starts the engine.
-	 */
-	engineForUser(userId: string): FeedEngine {
-		let engine = this.engines.get(userId)
-		if (!engine) {
-			engine = this.createEngine(userId)
-			this.engines.set(userId, engine)
-		}
-		return engine
-	}
-
-	/**
-	 * Refresh a user's feed.
-	 */
-	async refresh(userId: string): Promise<FeedResult> {
-		const engine = this.engineForUser(userId)
-		return engine.refresh()
-	}
-
-	/**
-	 * Subscribe to feed updates for a user.
-	 * Returns unsubscribe function.
-	 */
-	subscribe(userId: string, callback: FeedSubscriber): () => void {
-		const engine = this.engineForUser(userId)
-		return engine.subscribe(callback)
-	}
-
-	/**
-	 * Remove a user's FeedEngine.
-	 * Stops the engine and cleans up resources.
-	 */
-	removeUser(userId: string): void {
-		const engine = this.engines.get(userId)
-		if (engine) {
-			engine.stop()
-			this.engines.delete(userId)
-		}
-	}
-
-	private createEngine(userId: string): FeedEngine {
-		const engine = new FeedEngine()
-
-		for (const provider of this.providers) {
-			const source = provider.feedSourceForUser(userId)
-			engine.register(source)
-		}
-
-		engine.start()
-
-		return engine
-	}
-}

apps/aris-backend/src/location/router.ts

@@ -1,10 +1,7 @@
-import { TRPCError } from "@trpc/server"
 import { type } from "arktype"
 
+import type { UserSessionManager } from "../session/index.ts"
 import type { TRPC } from "../trpc/router.ts"
-import type { LocationService } from "./service.ts"
-
-import { UserNotFoundError } from "../lib/error.ts"
 
 const locationInput = type({
 	lat: "number",
@@ -15,23 +12,17 @@ const locationInput = type({
 
 export function createLocationRouter(
 	t: TRPC,
-	{ locationService }: { locationService: LocationService },
+	{ sessionManager }: { sessionManager: UserSessionManager },
 ) {
 	return t.router({
-		update: t.procedure.input(locationInput).mutation(({ input, ctx }) => {
-			try {
-				locationService.updateUserLocation(ctx.user.id, {
-					lat: input.lat,
-					lng: input.lng,
-					accuracy: input.accuracy,
-					timestamp: input.timestamp,
-				})
-			} catch (error) {
-				if (error instanceof UserNotFoundError) {
-					throw new TRPCError({ code: "NOT_FOUND", message: error.message })
-				}
-				throw error
-			}
+		update: t.procedure.input(locationInput).mutation(async ({ input, ctx }) => {
+			const session = sessionManager.getOrCreate(ctx.user.id)
+			await session.engine.executeAction("aris.location", "update-location", {
+				lat: input.lat,
+				lng: input.lng,
+				accuracy: input.accuracy,
+				timestamp: input.timestamp,
+			})
 		}),
 	})
 }

apps/aris-backend/src/location/service.test.ts

@@ -1,111 +0,0 @@
-import { describe, expect, test } from "bun:test"
-
-import { UserNotFoundError } from "../lib/error.ts"
-import { LocationService } from "./service.ts"
-
-describe("LocationService", () => {
-	test("feedSourceForUser creates source on first call", () => {
-		const service = new LocationService()
-		const source = service.feedSourceForUser("user-1")
-
-		expect(source).toBeDefined()
-		expect(source.id).toBe("location")
-	})
-
-	test("feedSourceForUser returns same source for same user", () => {
-		const service = new LocationService()
-		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 LocationService()
-		const source1 = service.feedSourceForUser("user-1")
-		const source2 = service.feedSourceForUser("user-2")
-
-		expect(source1).not.toBe(source2)
-	})
-
-	test("updateUserLocation updates the source", () => {
-		const service = new LocationService()
-		const source = service.feedSourceForUser("user-1")
-		const location = {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		}
-
-		service.updateUserLocation("user-1", location)
-
-		expect(source.lastLocation).toEqual(location)
-	})
-
-	test("updateUserLocation throws if source does not exist", () => {
-		const service = new LocationService()
-		const location = {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		}
-
-		expect(() => service.updateUserLocation("user-1", location)).toThrow(UserNotFoundError)
-	})
-
-	test("lastUserLocation returns null for unknown user", () => {
-		const service = new LocationService()
-
-		expect(service.lastUserLocation("unknown")).toBeNull()
-	})
-
-	test("lastUserLocation returns last location", () => {
-		const service = new LocationService()
-		service.feedSourceForUser("user-1")
-		const location1 = {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		}
-		const location2 = {
-			lat: 52.0,
-			lng: -0.2,
-			accuracy: 5,
-			timestamp: new Date(),
-		}
-
-		service.updateUserLocation("user-1", location1)
-		service.updateUserLocation("user-1", location2)
-
-		expect(service.lastUserLocation("user-1")).toEqual(location2)
-	})
-
-	test("removeUser removes the source", () => {
-		const service = new LocationService()
-		service.feedSourceForUser("user-1")
-		const location = {
-			lat: 51.5074,
-			lng: -0.1278,
-			accuracy: 10,
-			timestamp: new Date(),
-		}
-
-		service.updateUserLocation("user-1", location)
-		service.removeUser("user-1")
-
-		expect(service.lastUserLocation("user-1")).toBeNull()
-	})
-
-	test("removeUser allows new source to be created", () => {
-		const service = new LocationService()
-		const source1 = service.feedSourceForUser("user-1")
-
-		service.removeUser("user-1")
-		const source2 = service.feedSourceForUser("user-1")
-
-		expect(source1).not.toBe(source2)
-	})
-})

apps/aris-backend/src/location/service.ts

@@ -1,57 +0,0 @@
-import { LocationSource, type Location } from "@aris/source-location"
-
-import type { FeedSourceProvider } from "../feed/service.ts"
-
-import { UserNotFoundError } from "../lib/error.ts"
-
-/**
- * Manages LocationSource instances per user.
- */
-export class LocationService implements FeedSourceProvider {
-	private sources = new Map<string, LocationSource>()
-
-	/**
-	 * Get or create a LocationSource for a user.
-	 * @param userId - The user's unique identifier
-	 * @returns The user's LocationSource instance
-	 */
-	feedSourceForUser(userId: string): LocationSource {
-		let source = this.sources.get(userId)
-		if (!source) {
-			source = new LocationSource()
-			this.sources.set(userId, source)
-		}
-		return source
-	}
-
-	/**
-	 * Update location for a user.
-	 * @param userId - The user's unique identifier
-	 * @param location - The new location data
-	 * @throws {UserNotFoundError} If no source exists for the user
-	 */
-	updateUserLocation(userId: string, location: Location): void {
-		const source = this.sources.get(userId)
-		if (!source) {
-			throw new UserNotFoundError(userId)
-		}
-		source.pushLocation(location)
-	}
-
-	/**
-	 * Get last known location for a user.
-	 * @param userId - The user's unique identifier
-	 * @returns The last location, or null if none exists
-	 */
-	lastUserLocation(userId: string): Location | null {
-		return this.sources.get(userId)?.lastLocation ?? null
-	}
-
-	/**
-	 * Remove a user's LocationSource.
-	 * @param userId - The user's unique identifier
-	 */
-	removeUser(userId: string): void {
-		this.sources.delete(userId)
-	}
-}

apps/aris-backend/src/server.ts

@@ -1,25 +1,27 @@
+import { LocationSource } from "@aris/source-location"
 import { trpcServer } from "@hono/trpc-server"
 import { Hono } from "hono"
 
 import { registerAuthHandlers } from "./auth/http.ts"
-import { LocationService } from "./location/service.ts"
+import { UserSessionManager } from "./session/index.ts"
+import { WeatherSourceProvider } from "./weather/provider.ts"
 import { createContext } from "./trpc/context.ts"
 import { createTRPCRouter } from "./trpc/router.ts"
-import { WeatherService } from "./weather/service.ts"
 
 function main() {
-	const locationService = new LocationService()
+	const sessionManager = new UserSessionManager([
+		() => new LocationSource(),
+		new WeatherSourceProvider({
+			credentials: {
+				privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
+				keyId: process.env.WEATHERKIT_KEY_ID!,
+				teamId: process.env.WEATHERKIT_TEAM_ID!,
+				serviceId: process.env.WEATHERKIT_SERVICE_ID!,
+			},
+		}),
+	])
 
-	const weatherService = new WeatherService({
-		credentials: {
-			privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
-			keyId: process.env.WEATHERKIT_KEY_ID!,
-			teamId: process.env.WEATHERKIT_TEAM_ID!,
-			serviceId: process.env.WEATHERKIT_SERVICE_ID!,
-		},
-	})
-
-	const trpcRouter = createTRPCRouter({ locationService, weatherService })
+	const trpcRouter = createTRPCRouter({ sessionManager })
 
 	const app = new Hono()
 

apps/aris-backend/src/session/feed-source-provider.ts

@@ -0,0 +1,9 @@
+import type { FeedSource } from "@aris/core"
+
+export interface FeedSourceProvider {
+	feedSourceForUser(userId: string): FeedSource
+}
+
+export type FeedSourceProviderFn = (userId: string) => FeedSource
+
+export type FeedSourceProviderInput = FeedSourceProvider | FeedSourceProviderFn

apps/aris-backend/src/session/index.ts

@@ -0,0 +1,7 @@
+export type {
+	FeedSourceProvider,
+	FeedSourceProviderFn,
+	FeedSourceProviderInput,
+} from "./feed-source-provider.ts"
+export { UserSession } from "./user-session.ts"
+export { UserSessionManager } from "./user-session-manager.ts"

apps/aris-backend/src/session/user-session-manager.test.ts

@@ -0,0 +1,166 @@
+import { LocationSource } from "@aris/source-location"
+import { describe, expect, mock, test } from "bun:test"
+
+import { WeatherSourceProvider } from "../weather/provider.ts"
+import { UserSessionManager } from "./user-session-manager.ts"
+
+import type { WeatherKitClient, WeatherKitResponse } from "@aris/source-weatherkit"
+
+const mockWeatherClient: WeatherKitClient = {
+	fetch: async () => ({}) as WeatherKitResponse,
+}
+
+describe("UserSessionManager", () => {
+	test("getOrCreate creates session on first call", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session).toBeDefined()
+		expect(session.engine).toBeDefined()
+	})
+
+	test("getOrCreate returns same session for same user", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-1")
+
+		expect(session1).toBe(session2)
+	})
+
+	test("getOrCreate returns different sessions for different users", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-2")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("each user gets independent source instances", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-2")
+
+		const source1 = session1.getSource<LocationSource>("aris.location")
+		const source2 = session2.getSource<LocationSource>("aris.location")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("remove destroys session and allows re-creation", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		manager.remove("user-1")
+		const session2 = manager.getOrCreate("user-1")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("remove is no-op for unknown user", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		expect(() => manager.remove("unknown")).not.toThrow()
+	})
+
+	test("accepts function providers", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+		const result = await session.engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("accepts object providers", () => {
+		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
+		const manager = new UserSessionManager([() => new LocationSource(), provider])
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session.getSource("aris.weather")).toBeDefined()
+	})
+
+	test("accepts mixed providers", () => {
+		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
+		const manager = new UserSessionManager([() => new LocationSource(), provider])
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session.getSource("aris.location")).toBeDefined()
+		expect(session.getSource("aris.weather")).toBeDefined()
+	})
+
+	test("refresh returns feed result through session", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+		const result = await session.engine.refresh()
+
+		expect(result).toHaveProperty("context")
+		expect(result).toHaveProperty("items")
+		expect(result).toHaveProperty("errors")
+		expect(result.context.time).toBeInstanceOf(Date)
+	})
+
+	test("location update via executeAction works", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+		await session.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		const source = session.getSource<LocationSource>("aris.location")
+		expect(source?.lastLocation?.lat).toBe(51.5074)
+	})
+
+	test("subscribe receives updates after location push", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+		const callback = mock()
+
+		const session = manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		await session.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		// Wait for async update propagation
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).toHaveBeenCalled()
+	})
+
+	test("remove stops reactive updates", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+		const callback = mock()
+
+		const session = manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		manager.remove("user-1")
+
+		// Create new session and push location — old callback should not fire
+		const session2 = manager.getOrCreate("user-1")
+		await session2.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).not.toHaveBeenCalled()
+	})
+})

apps/aris-backend/src/session/user-session-manager.ts

@@ -0,0 +1,31 @@
+import type { FeedSourceProviderInput } from "./feed-source-provider.ts"
+import { UserSession } from "./user-session.ts"
+
+export class UserSessionManager {
+	private sessions = new Map<string, UserSession>()
+	private readonly providers: FeedSourceProviderInput[]
+
+	constructor(providers: FeedSourceProviderInput[]) {
+		this.providers = providers
+	}
+
+	getOrCreate(userId: string): UserSession {
+		let session = this.sessions.get(userId)
+		if (!session) {
+			const sources = this.providers.map((p) =>
+				typeof p === "function" ? p(userId) : p.feedSourceForUser(userId),
+			)
+			session = new UserSession(sources)
+			this.sessions.set(userId, session)
+		}
+		return session
+	}
+
+	remove(userId: string): void {
+		const session = this.sessions.get(userId)
+		if (session) {
+			session.destroy()
+			this.sessions.delete(userId)
+		}
+	}
+}

apps/aris-backend/src/session/user-session.test.ts

@@ -0,0 +1,72 @@
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+
+import { LocationSource } from "@aris/source-location"
+import { describe, expect, test } from "bun:test"
+
+import { UserSession } from "./user-session.ts"
+
+function createStubSource(id: string): FeedSource {
+	return {
+		id,
+		async listActions(): Promise<Record<string, ActionDefinition>> {
+			return {}
+		},
+		async executeAction(): Promise<unknown> {
+			return undefined
+		},
+		async fetchContext(): Promise<Partial<Context> | null> {
+			return null
+		},
+		async fetchItems() {
+			return []
+		},
+	}
+}
+
+describe("UserSession", () => {
+	test("registers sources and starts engine", async () => {
+		const session = new UserSession([createStubSource("test-a"), createStubSource("test-b")])
+
+		const result = await session.engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("getSource returns registered source", () => {
+		const location = new LocationSource()
+		const session = new UserSession([location])
+
+		const result = session.getSource<LocationSource>("aris.location")
+
+		expect(result).toBe(location)
+	})
+
+	test("getSource returns undefined for unknown source", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		expect(session.getSource("unknown")).toBeUndefined()
+	})
+
+	test("destroy stops engine and clears sources", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		session.destroy()
+
+		expect(session.getSource("test")).toBeUndefined()
+	})
+
+	test("engine.executeAction routes to correct source", async () => {
+		const location = new LocationSource()
+		const session = new UserSession([location])
+
+		await session.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5,
+			lng: -0.1,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		expect(location.lastLocation).toBeDefined()
+		expect(location.lastLocation!.lat).toBe(51.5)
+	})
+})

apps/aris-backend/src/session/user-session.ts

@@ -0,0 +1,24 @@
+import { FeedEngine, type FeedSource } from "@aris/core"
+
+export class UserSession {
+	readonly engine: FeedEngine
+	private sources = new Map<string, FeedSource>()
+
+	constructor(sources: FeedSource[]) {
+		this.engine = new FeedEngine()
+		for (const source of sources) {
+			this.sources.set(source.id, source)
+			this.engine.register(source)
+		}
+		this.engine.start()
+	}
+
+	getSource<T extends FeedSource>(sourceId: string): T | undefined {
+		return this.sources.get(sourceId) as T | undefined
+	}
+
+	destroy(): void {
+		this.engine.stop()
+		this.sources.clear()
+	}
+}

apps/aris-backend/src/tfl/provider.ts

@@ -0,0 +1,19 @@
+import { TflSource, type ITflApi } from "@aris/source-tfl"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export type TflSourceProviderOptions =
+	| { apiKey: string; client?: never }
+	| { apiKey?: never; client: ITflApi }
+
+export class TflSourceProvider implements FeedSourceProvider {
+	private readonly options: TflSourceProviderOptions
+
+	constructor(options: TflSourceProviderOptions) {
+		this.options = options
+	}
+
+	feedSourceForUser(_userId: string): TflSource {
+		return new TflSource(this.options)
+	}
+}

apps/aris-backend/src/tfl/service.test.ts

@@ -1,206 +0,0 @@
-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("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("tfl")
-		expect(service.feedSourceForUser("user-2").id).toBe("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")
-		})
-	})
-})

apps/aris-backend/src/tfl/service.ts

@@ -1,40 +0,0 @@
-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)
-	}
-}

apps/aris-backend/src/trpc/router.ts

@@ -1,16 +1,26 @@
 import { initTRPC, TRPCError } from "@trpc/server"
 
-import type { LocationService } from "../location/service.ts"
-import type { WeatherService } from "../weather/service.ts"
+import type { UserSessionManager } from "../session/index.ts"
 import type { Context } from "./context.ts"
 
 import { createLocationRouter } from "../location/router.ts"
 
-interface AuthedContext {
-	user: NonNullable<Context["user"]>
-	session: NonNullable<Context["session"]>
+export type TRPC = ReturnType<typeof createTRPC>
+
+export interface TRPCRouterDeps {
+	sessionManager: UserSessionManager
 }
 
+export function createTRPCRouter({ sessionManager }: TRPCRouterDeps) {
+	const t = createTRPC()
+
+	return t.router({
+		location: createLocationRouter(t, { sessionManager }),
+	})
+}
+
+export type TRPCRouter = ReturnType<typeof createTRPCRouter>
+
 function createTRPC() {
 	const t = initTRPC.context<Context>().create()
 
@@ -32,19 +42,3 @@ function createTRPC() {
 	}
 }
 
-export type TRPC = ReturnType<typeof createTRPC>
-
-export interface TRPCRouterDeps {
-	locationService: LocationService
-	weatherService: WeatherService
-}
-
-export function createTRPCRouter({ locationService }: TRPCRouterDeps) {
-	const t = createTRPC()
-
-	return t.router({
-		location: createLocationRouter(t, { locationService }),
-	})
-}
-
-export type TRPCRouter = ReturnType<typeof createTRPCRouter>

apps/aris-backend/src/weather/provider.ts

@@ -0,0 +1,15 @@
+import { WeatherSource, type WeatherSourceOptions } from "@aris/source-weatherkit"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export class WeatherSourceProvider implements FeedSourceProvider {
+	private readonly options: WeatherSourceOptions
+
+	constructor(options: WeatherSourceOptions) {
+		this.options = options
+	}
+
+	feedSourceForUser(_userId: string): WeatherSource {
+		return new WeatherSource(this.options)
+	}
+}

apps/aris-backend/src/weather/service.test.ts

@@ -1,116 +0,0 @@
-import type { Context } from "@aris/core"
-
-import { LocationKey } from "@aris/source-location"
-import {
-	Units,
-	WeatherFeedItemType,
-	type WeatherKitClient,
-	type WeatherKitResponse,
-} from "@aris/source-weatherkit"
-import { describe, expect, test } from "bun:test"
-
-import fixture from "../../../../packages/aris-source-weatherkit/fixtures/san-francisco.json"
-import { WeatherService } from "./service.ts"
-
-const mockClient = createMockClient(fixture.response as WeatherKitResponse)
-
-function createMockClient(response: WeatherKitResponse): WeatherKitClient {
-	return {
-		fetch: async () => response,
-	}
-}
-
-function createMockContext(location?: { lat: number; lng: number }): Context {
-	const ctx: Context = { time: new Date("2026-01-17T00:00:00Z") }
-	if (location) {
-		ctx[LocationKey] = { ...location, accuracy: 10, timestamp: new Date() }
-	}
-	return ctx
-}
-
-describe("WeatherService", () => {
-	test("feedSourceForUser creates source on first call", () => {
-		const service = new WeatherService({ client: mockClient })
-		const source = service.feedSourceForUser("user-1")
-
-		expect(source).toBeDefined()
-		expect(source.id).toBe("weather")
-	})
-
-	test("feedSourceForUser returns same source for same user", () => {
-		const service = new WeatherService({ client: mockClient })
-		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 WeatherService({ client: mockClient })
-		const source1 = service.feedSourceForUser("user-1")
-		const source2 = service.feedSourceForUser("user-2")
-
-		expect(source1).not.toBe(source2)
-	})
-
-	test("feedSourceForUser applies hourly and daily limits", async () => {
-		const service = new WeatherService({
-			client: mockClient,
-			hourlyLimit: 3,
-			dailyLimit: 2,
-		})
-		const source = service.feedSourceForUser("user-1")
-		const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
-
-		const items = await source.fetchItems(context)
-
-		const hourly = items.filter((i) => i.type === WeatherFeedItemType.hourly)
-		const daily = items.filter((i) => i.type === WeatherFeedItemType.daily)
-
-		expect(hourly).toHaveLength(3)
-		expect(daily).toHaveLength(2)
-	})
-
-	test("feedSourceForUser applies units", async () => {
-		const service = new WeatherService({
-			client: mockClient,
-			units: Units.imperial,
-		})
-		const source = service.feedSourceForUser("user-1")
-		const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
-
-		const items = await source.fetchItems(context)
-		const current = items.find((i) => i.type === WeatherFeedItemType.current)
-
-		expect(current).toBeDefined()
-		// Fixture has ~15.87°C, imperial should be ~60.6°F
-		expect(current!.data.temperature).toBeGreaterThan(50)
-	})
-
-	test("removeUser removes the source", () => {
-		const service = new WeatherService({ client: mockClient })
-		service.feedSourceForUser("user-1")
-
-		service.removeUser("user-1")
-
-		// After removal, feedSourceForUser should create a new instance
-		const source2 = service.feedSourceForUser("user-1")
-		expect(source2).toBeDefined()
-	})
-
-	test("removeUser allows new source to be created", () => {
-		const service = new WeatherService({ client: mockClient })
-		const source1 = service.feedSourceForUser("user-1")
-
-		service.removeUser("user-1")
-		const source2 = service.feedSourceForUser("user-1")
-
-		expect(source1).not.toBe(source2)
-	})
-
-	test("removeUser is no-op for unknown user", () => {
-		const service = new WeatherService({ client: mockClient })
-
-		expect(() => service.removeUser("unknown")).not.toThrow()
-	})
-})

apps/aris-backend/src/weather/service.ts

@@ -1,40 +0,0 @@
-import { WeatherSource, type WeatherSourceOptions } from "@aris/source-weatherkit"
-
-import type { FeedSourceProvider } from "../feed/service.ts"
-
-/**
- * Options forwarded to every per-user WeatherSource.
- * Must include either `credentials` or `client` (same requirement as WeatherSourceOptions).
- */
-export type WeatherServiceOptions = WeatherSourceOptions
-
-/**
- * Manages WeatherSource instances per user.
- */
-export class WeatherService implements FeedSourceProvider {
-	private sources = new Map<string, WeatherSource>()
-	private readonly options: WeatherServiceOptions
-
-	constructor(options: WeatherServiceOptions) {
-		this.options = options
-	}
-
-	/**
-	 * Get or create a WeatherSource for a user.
-	 */
-	feedSourceForUser(userId: string): WeatherSource {
-		let source = this.sources.get(userId)
-		if (!source) {
-			source = new WeatherSource(this.options)
-			this.sources.set(userId, source)
-		}
-		return source
-	}
-
-	/**
-	 * Remove a user's WeatherSource.
-	 */
-	removeUser(userId: string): void {
-		this.sources.delete(userId)
-	}
-}

bun.lock

@@ -35,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",
@@ -66,6 +69,7 @@
       "version": "0.0.0",
       "dependencies": {
         "@aris/core": "workspace:*",
+        "arktype": "^2.1.0",
       },
     },
     "packages/aris-source-tfl": {

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?

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)

packages/aris-core/package.json

@@ -6,5 +6,8 @@
 	"types": "src/index.ts",
 	"scripts": {
 		"test": "bun test ."
+	},
+	"dependencies": {
+		"@standard-schema/spec": "^1.1.0"
 	}
 }

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>
+}

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,6 +82,7 @@ function createWeatherSource(
 	return {
 		id: "weather",
 		dependencies: ["location"],
+		...noActions,
 
 		async fetchContext(context) {
 			const location = contextValue(context, LocationKey)
@@ -104,6 +116,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 	return {
 		id: "alert",
 		dependencies: ["weather"],
+		...noActions,
 
 		async fetchContext() {
 			return null
@@ -168,11 +181,12 @@ 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
 				},
@@ -180,16 +194,17 @@ describe("FeedEngine", () => {
 
 			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"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -197,6 +212,7 @@ describe("FeedEngine", () => {
 			const b: FeedSource = {
 				id: "b",
 				dependencies: ["a"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -204,14 +220,15 @@ describe("FeedEngine", () => {
 
 			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"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -219,6 +236,7 @@ describe("FeedEngine", () => {
 			const b: FeedSource = {
 				id: "b",
 				dependencies: ["a"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -226,6 +244,7 @@ describe("FeedEngine", () => {
 			const c: FeedSource = {
 				id: "c",
 				dependencies: ["b"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -233,7 +252,7 @@ describe("FeedEngine", () => {
 
 			engine.register(a).register(b).register(c)
 
-			expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
+			await expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
 		})
 	})
 
@@ -243,6 +262,7 @@ describe("FeedEngine", () => {
 
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					order.push("location")
 					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -252,6 +272,7 @@ describe("FeedEngine", () => {
 			const weather: FeedSource = {
 				id: "weather",
 				dependencies: ["location"],
+				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
 					const loc = contextValue(ctx, LocationKey)
@@ -277,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 () => {
@@ -318,6 +345,7 @@ describe("FeedEngine", () => {
 		test("handles missing upstream context gracefully", async () => {
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					return null // No location available
 				},
@@ -336,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")
 				},
@@ -353,6 +382,7 @@ describe("FeedEngine", () => {
 		test("captures errors from fetchItems", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -373,6 +403,7 @@ describe("FeedEngine", () => {
 		test("continues after source error", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
 				async fetchContext() {
 					throw new Error("Failed")
 				},
@@ -380,6 +411,7 @@ describe("FeedEngine", () => {
 
 			const working: FeedSource = {
 				id: "working",
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -423,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,
+			})
 		})
 	})
 
@@ -498,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"',
+			)
+		})
+	})
 })

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"
@@ -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()))
@@ -240,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[] {

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,6 +81,7 @@ function createWeatherSource(
 	return {
 		id: "weather",
 		dependencies: ["location"],
+		...noActions,
 
 		async fetchContext(context) {
 			const location = contextValue(context, LocationKey)
@@ -103,6 +115,7 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 	return {
 		id: "alert",
 		dependencies: ["weather"],
+		...noActions,
 
 		async fetchContext() {
 			return null
@@ -265,6 +278,7 @@ describe("FeedSource", () => {
 			const orphan: FeedSource = {
 				id: "orphan",
 				dependencies: ["nonexistent"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -279,6 +293,7 @@ describe("FeedSource", () => {
 			const a: FeedSource = {
 				id: "a",
 				dependencies: ["b"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -286,6 +301,7 @@ describe("FeedSource", () => {
 			const b: FeedSource = {
 				id: "b",
 				dependencies: ["a"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -298,6 +314,7 @@ describe("FeedSource", () => {
 			const a: FeedSource = {
 				id: "a",
 				dependencies: ["c"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -305,6 +322,7 @@ describe("FeedSource", () => {
 			const b: FeedSource = {
 				id: "b",
 				dependencies: ["a"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -312,6 +330,7 @@ describe("FeedSource", () => {
 			const c: FeedSource = {
 				id: "c",
 				dependencies: ["b"],
+				...noActions,
 				async fetchContext() {
 					return null
 				},
@@ -350,6 +369,7 @@ describe("FeedSource", () => {
 
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					order.push("location")
 					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -359,6 +379,7 @@ describe("FeedSource", () => {
 			const weather: FeedSource = {
 				id: "weather",
 				dependencies: ["location"],
+				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
 					const loc = contextValue(ctx, LocationKey)
@@ -382,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 () => {
@@ -422,6 +449,7 @@ describe("FeedSource", () => {
 			// Location source exists but hasn't been updated
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					// Simulate no location available
 					return null

packages/aris-core/src/feed-source.ts

@@ -1,61 +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)
- *   },
- * }
- *
- * // TFL source - no context to provide
- * const tflSource: FeedSource<TflFeedItem> = {
- *   id: "tfl",
- *   fetchContext: async () => null,
- *   fetchItems: async (ctx) => { ... },
+ *   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,
@@ -66,6 +65,7 @@ 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> | null>
 
@@ -73,12 +73,14 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
 	 * 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[]>
 }

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"
 

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)

packages/aris-source-apple-calendar/src/calendar-source.test.ts

@@ -78,7 +78,7 @@ class MockDAVClient implements CalendarDAVClient {
 describe("CalendarSource", () => {
 	test("has correct id", () => {
 		const source = new CalendarSource(new NullCredentialProvider(), "user-1")
-		expect(source.id).toBe("apple-calendar")
+		expect(source.id).toBe("aris.apple-calendar")
 	})
 
 	test("returns empty array when credentials are null", async () => {
@@ -121,7 +121,10 @@ describe("CalendarSource", () => {
 		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") },
+				{
+					url: "/cal/personal/event2.ics",
+					data: loadFixture("all-day-event.ics"),
+				},
 			],
 		}
 		const client = new MockDAVClient(
@@ -206,7 +209,12 @@ describe("CalendarSource", () => {
 
 	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") }],
+			"/cal/weird": [
+				{
+					url: "/cal/weird/event1.ics",
+					data: loadFixture("minimal-event.ics"),
+				},
+			],
 		}
 		const client = new MockDAVClient(
 			[{ url: "/cal/weird", displayName: { _cdata: "Weird Calendar" } }],
@@ -222,7 +230,12 @@ describe("CalendarSource", () => {
 
 	test("handles recurring events with exceptions", async () => {
 		const objects: Record<string, CalendarDAVObject[]> = {
-			"/cal/work": [{ url: "/cal/work/recurring.ics", data: loadFixture("recurring-event.ics") }],
+			"/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", {

packages/aris-source-apple-calendar/src/calendar-source.ts

@@ -1,4 +1,5 @@
-import type { Context, FeedSource } from "@aris/core"
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+import { UnknownActionError } from "@aris/core"
 
 import { DAVClient } from "tsdav"
 
@@ -37,7 +38,7 @@ const DEFAULT_LOOK_AHEAD_DAYS = 0
  * ```
  */
 export class CalendarSource implements FeedSource<CalendarFeedItem> {
-	readonly id = "apple-calendar"
+	readonly id = "aris.apple-calendar"
 
 	private readonly credentialProvider: CalendarCredentialProvider
 	private readonly userId: string
@@ -58,6 +59,14 @@ export class CalendarSource implements FeedSource<CalendarFeedItem> {
 		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) {

packages/aris-source-google-calendar/src/google-calendar-source.test.ts

@@ -45,13 +45,15 @@ describe("GoogleCalendarSource", () => {
 	describe("constructor", () => {
 		test("has correct id", () => {
 			const source = new GoogleCalendarSource({ client: defaultMockClient() })
-			expect(source.id).toBe("google-calendar")
+			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 source = new GoogleCalendarSource({
+				client: createMockClient({ primary: [] }),
+			})
 			const items = await source.fetchItems(createContext())
 			expect(items).toEqual([])
 		})
@@ -198,7 +200,9 @@ describe("GoogleCalendarSource", () => {
 
 	describe("fetchContext", () => {
 		test("returns null when no events", async () => {
-			const source = new GoogleCalendarSource({ client: createMockClient({ primary: [] }) })
+			const source = new GoogleCalendarSource({
+				client: createMockClient({ primary: [] }),
+			})
 			const result = await source.fetchContext(createContext())
 			expect(result).toBeNull()
 		})

packages/aris-source-google-calendar/src/google-calendar-source.ts

@@ -1,4 +1,6 @@
-import type { Context, FeedSource } from "@aris/core"
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+
+import { UnknownActionError } from "@aris/core"
 
 import type {
 	ApiCalendarEvent,
@@ -63,7 +65,7 @@ const PRIORITY_ALL_DAY = 0.4
  * ```
  */
 export class GoogleCalendarSource implements FeedSource<CalendarFeedItem> {
-	readonly id = "google-calendar"
+	readonly id = "aris.google-calendar"
 
 	private readonly client: GoogleCalendarClient
 	private readonly calendarIds: string[] | undefined
@@ -75,6 +77,14 @@ export class GoogleCalendarSource implements FeedSource<CalendarFeedItem> {
 		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)
 

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"
 	}
 }

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"

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 () => {
@@ -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")
+		})
+	})
 })

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.
 	 */

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
+}

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'",
 )
 

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", () => {
@@ -122,7 +122,12 @@ describe("TflSource", () => {
 						severity: "minor-delays",
 						description: "Delays",
 					},
-					{ lineId: "central", lineName: "Central", severity: "closure", description: "Closed" },
+					{
+						lineId: "central",
+						lineName: "Central",
+						severity: "closure",
+						description: "Closed",
+					},
 				]
 				return lines ? all.filter((s) => lines.includes(s.lineId)) : all
 			},
@@ -144,7 +149,10 @@ describe("TflSource", () => {
 		})
 
 		test("DEFAULT_LINES_OF_INTEREST restores all lines", async () => {
-			const source = new TflSource({ client: lineFilteringApi, lines: ["northern"] })
+			const source = new TflSource({
+				client: lineFilteringApi,
+				lines: ["northern"],
+			})
 			const filtered = await source.fetchItems(createContext())
 			expect(filtered.length).toBe(1)
 
@@ -164,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) {
@@ -178,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) {
@@ -230,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) {
@@ -248,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", () => {

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,
@@ -63,8 +66,8 @@ export class TflSource implements FeedSource<TflAlertFeedItem> {
 		"elizabeth",
 	]
 
-	readonly id = "tfl"
-	readonly dependencies = ["location"]
+	readonly id = "aris.tfl"
+	readonly dependencies = ["aris.location"]
 
 	private readonly client: ITflApi
 	private lines: TflLineId[]
@@ -77,6 +80,31 @@ export class TflSource implements FeedSource<TflAlertFeedItem> {
 		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
 	}

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", () => {
@@ -78,7 +78,10 @@ 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)

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,6 +111,14 @@ export class WeatherSource implements FeedSource<WeatherFeedItem> {
 		this.units = options.units ?? Units.metric
 	}
 
+	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) {