Merge pull request #14 from kennethnym/feat/feed-engine

feat(core): add FeedEngine for FeedSource orchestration

bun.lock

@@ -33,6 +33,22 @@
         "arktype": "^2.1.0",
       },
     },
+    "packages/aris-source-location": {
+      "name": "@aris/source-location",
+      "version": "0.0.0",
+      "dependencies": {
+        "@aris/core": "workspace:*",
+      },
+    },
+    "packages/aris-source-weatherkit": {
+      "name": "@aris/source-weatherkit",
+      "version": "0.0.0",
+      "dependencies": {
+        "@aris/core": "workspace:*",
+        "@aris/source-location": "workspace:*",
+        "arktype": "^2.1.0",
+      },
+    },
   },
   "packages": {
     "@aris/core": ["@aris/core@workspace:packages/aris-core"],
@@ -41,6 +57,10 @@
 
     "@aris/data-source-weatherkit": ["@aris/data-source-weatherkit@workspace:packages/aris-data-source-weatherkit"],
 
+    "@aris/source-location": ["@aris/source-location@workspace:packages/aris-source-location"],
+
+    "@aris/source-weatherkit": ["@aris/source-weatherkit@workspace:packages/aris-source-weatherkit"],
+
     "@ark/schema": ["@ark/schema@0.56.0", "", { "dependencies": { "@ark/util": "0.56.0" } }, "sha512-ECg3hox/6Z/nLajxXqNhgPtNdHWC9zNsDyskwO28WinoFEnWow4IsERNz9AnXRhTZJnYIlAJ4uGn3nlLk65vZA=="],
 
     "@ark/util": ["@ark/util@0.56.0", "", {}, "sha512-BghfRC8b9pNs3vBoDJhcta0/c1J1rsoS1+HgVUreMFPdhz/CRAKReAu57YEllNaSy98rWAdY1gE+gFup7OXpgA=="],

packages/aris-core/src/feed-engine.test.ts

@@ -0,0 +1,458 @@
+import { describe, expect, test } from "bun:test"
+
+import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
+
+import { FeedEngine } from "./feed-engine"
+import { contextKey, contextValue } from "./index"
+
+// =============================================================================
+// CONTEXT KEYS
+// =============================================================================
+
+interface Location {
+	lat: number
+	lng: number
+}
+
+interface Weather {
+	temperature: number
+	condition: string
+}
+
+const LocationKey: ContextKey<Location> = contextKey("location")
+const WeatherKey: ContextKey<Weather> = contextKey("weather")
+
+// =============================================================================
+// FEED ITEMS
+// =============================================================================
+
+type WeatherFeedItem = FeedItem<"weather", { temperature: number; condition: string }>
+type AlertFeedItem = FeedItem<"alert", { message: string }>
+
+// =============================================================================
+// TEST HELPERS
+// =============================================================================
+
+interface SimulatedLocationSource extends FeedSource {
+	simulateUpdate(location: Location): void
+}
+
+function createLocationSource(): SimulatedLocationSource {
+	let callback: ((update: Partial<Context>) => void) | null = null
+	let currentLocation: Location = { lat: 0, lng: 0 }
+
+	return {
+		id: "location",
+
+		onContextUpdate(cb) {
+			callback = cb
+			return () => {
+				callback = null
+			}
+		},
+
+		async fetchContext() {
+			return { [LocationKey]: currentLocation }
+		},
+
+		simulateUpdate(location: Location) {
+			currentLocation = location
+			callback?.({ [LocationKey]: location })
+		},
+	}
+}
+
+function createWeatherSource(
+	fetchWeather: (location: Location) => Promise<Weather> = async () => ({
+		temperature: 20,
+		condition: "sunny",
+	}),
+): FeedSource<WeatherFeedItem> {
+	return {
+		id: "weather",
+		dependencies: ["location"],
+
+		async fetchContext(context) {
+			const location = contextValue(context, LocationKey)
+			if (!location) return {}
+
+			const weather = await fetchWeather(location)
+			return { [WeatherKey]: weather }
+		},
+
+		async fetchItems(context) {
+			const weather = contextValue(context, WeatherKey)
+			if (!weather) return []
+
+			return [
+				{
+					id: `weather-${Date.now()}`,
+					type: "weather",
+					priority: 0.5,
+					timestamp: new Date(),
+					data: {
+						temperature: weather.temperature,
+						condition: weather.condition,
+					},
+				},
+			]
+		},
+	}
+}
+
+function createAlertSource(): FeedSource<AlertFeedItem> {
+	return {
+		id: "alert",
+		dependencies: ["weather"],
+
+		async fetchItems(context) {
+			const weather = contextValue(context, WeatherKey)
+			if (!weather) return []
+
+			if (weather.condition === "storm") {
+				return [
+					{
+						id: "alert-storm",
+						type: "alert",
+						priority: 1.0,
+						timestamp: new Date(),
+						data: { message: "Storm warning!" },
+					},
+				]
+			}
+
+			return []
+		},
+	}
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe("FeedEngine", () => {
+	describe("registration", () => {
+		test("registers sources", () => {
+			const engine = new FeedEngine()
+			const location = createLocationSource()
+
+			engine.register(location)
+
+			// Can refresh without error
+			expect(engine.refresh()).resolves.toBeDefined()
+		})
+
+		test("unregisters sources", async () => {
+			const engine = new FeedEngine()
+			const location = createLocationSource()
+
+			engine.register(location)
+			engine.unregister("location")
+
+			const result = await engine.refresh()
+			expect(result.items).toHaveLength(0)
+		})
+
+		test("allows chained registration", () => {
+			const engine = new FeedEngine()
+				.register(createLocationSource())
+				.register(createWeatherSource())
+				.register(createAlertSource())
+
+			expect(engine.refresh()).resolves.toBeDefined()
+		})
+	})
+
+	describe("graph validation", () => {
+		test("throws on missing dependency", () => {
+			const engine = new FeedEngine()
+			const orphan: FeedSource = {
+				id: "orphan",
+				dependencies: ["nonexistent"],
+			}
+
+			engine.register(orphan)
+
+			expect(engine.refresh()).rejects.toThrow(
+				'Source "orphan" depends on "nonexistent" which is not registered',
+			)
+		})
+
+		test("throws on circular dependency", () => {
+			const engine = new FeedEngine()
+			const a: FeedSource = { id: "a", dependencies: ["b"] }
+			const b: FeedSource = { id: "b", dependencies: ["a"] }
+
+			engine.register(a).register(b)
+
+			expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
+		})
+
+		test("throws on longer cycles", () => {
+			const engine = new FeedEngine()
+			const a: FeedSource = { id: "a", dependencies: ["c"] }
+			const b: FeedSource = { id: "b", dependencies: ["a"] }
+			const c: FeedSource = { id: "c", dependencies: ["b"] }
+
+			engine.register(a).register(b).register(c)
+
+			expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
+		})
+	})
+
+	describe("refresh", () => {
+		test("runs fetchContext in dependency order", async () => {
+			const order: string[] = []
+
+			const location: FeedSource = {
+				id: "location",
+				async fetchContext() {
+					order.push("location")
+					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
+				},
+			}
+
+			const weather: FeedSource = {
+				id: "weather",
+				dependencies: ["location"],
+				async fetchContext(ctx) {
+					order.push("weather")
+					const loc = contextValue(ctx, LocationKey)
+					expect(loc).toBeDefined()
+					return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
+				},
+			}
+
+			const engine = new FeedEngine().register(weather).register(location)
+
+			await engine.refresh()
+
+			expect(order).toEqual(["location", "weather"])
+		})
+
+		test("accumulates context across sources", async () => {
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			const weather = createWeatherSource()
+
+			const engine = new FeedEngine().register(location).register(weather)
+
+			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" })
+		})
+
+		test("collects items from all sources", async () => {
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			const weather = createWeatherSource()
+
+			const engine = new FeedEngine().register(location).register(weather)
+
+			const { items } = await engine.refresh()
+
+			expect(items).toHaveLength(1)
+			expect(items[0]!.type).toBe("weather")
+		})
+
+		test("sorts items by priority descending", async () => {
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			const weather = createWeatherSource(async () => ({
+				temperature: 15,
+				condition: "storm",
+			}))
+
+			const alert = createAlertSource()
+
+			const engine = new FeedEngine().register(location).register(weather).register(alert)
+
+			const { items } = await engine.refresh()
+
+			expect(items).toHaveLength(2)
+			expect(items[0]!.type).toBe("alert") // priority 1.0
+			expect(items[1]!.type).toBe("weather") // priority 0.5
+		})
+
+		test("handles missing upstream context gracefully", async () => {
+			const location: FeedSource = {
+				id: "location",
+				async fetchContext() {
+					return {} // No location available
+				},
+			}
+
+			const weather = createWeatherSource()
+
+			const engine = new FeedEngine().register(location).register(weather)
+
+			const { context, items } = await engine.refresh()
+
+			expect(contextValue(context, WeatherKey)).toBeUndefined()
+			expect(items).toHaveLength(0)
+		})
+
+		test("captures errors from fetchContext", async () => {
+			const failing: FeedSource = {
+				id: "failing",
+				async fetchContext() {
+					throw new Error("Context fetch failed")
+				},
+			}
+
+			const engine = new FeedEngine().register(failing)
+
+			const { errors } = await engine.refresh()
+
+			expect(errors).toHaveLength(1)
+			expect(errors[0]!.sourceId).toBe("failing")
+			expect(errors[0]!.error.message).toBe("Context fetch failed")
+		})
+
+		test("captures errors from fetchItems", async () => {
+			const failing: FeedSource = {
+				id: "failing",
+				async fetchItems() {
+					throw new Error("Items fetch failed")
+				},
+			}
+
+			const engine = new FeedEngine().register(failing)
+
+			const { errors } = await engine.refresh()
+
+			expect(errors).toHaveLength(1)
+			expect(errors[0]!.sourceId).toBe("failing")
+			expect(errors[0]!.error.message).toBe("Items fetch failed")
+		})
+
+		test("continues after source error", async () => {
+			const failing: FeedSource = {
+				id: "failing",
+				async fetchContext() {
+					throw new Error("Failed")
+				},
+			}
+
+			const working: FeedSource = {
+				id: "working",
+				async fetchItems() {
+					return [
+						{
+							id: "item-1",
+							type: "test",
+							priority: 0.5,
+							timestamp: new Date(),
+							data: {},
+						},
+					]
+				},
+			}
+
+			const engine = new FeedEngine().register(failing).register(working)
+
+			const { items, errors } = await engine.refresh()
+
+			expect(errors).toHaveLength(1)
+			expect(items).toHaveLength(1)
+		})
+	})
+
+	describe("currentContext", () => {
+		test("returns initial context before refresh", () => {
+			const engine = new FeedEngine()
+
+			const context = engine.currentContext()
+
+			expect(context.time).toBeInstanceOf(Date)
+		})
+
+		test("returns accumulated context after refresh", async () => {
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			const engine = new FeedEngine().register(location)
+
+			await engine.refresh()
+
+			const context = engine.currentContext()
+			expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
+		})
+	})
+
+	describe("subscribe", () => {
+		test("returns unsubscribe function", () => {
+			const engine = new FeedEngine()
+			let callCount = 0
+
+			const unsubscribe = engine.subscribe(() => {
+				callCount++
+			})
+
+			unsubscribe()
+
+			// Subscriber should not be called after unsubscribe
+			expect(callCount).toBe(0)
+		})
+	})
+
+	describe("reactive updates", () => {
+		test("start subscribes to onContextUpdate", async () => {
+			const location = createLocationSource()
+			const weather = createWeatherSource()
+
+			const engine = new FeedEngine().register(location).register(weather)
+
+			const results: Array<{ items: FeedItem[] }> = []
+			engine.subscribe((result) => {
+				results.push({ items: result.items })
+			})
+
+			engine.start()
+
+			// Simulate location update
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			// Wait for async refresh
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(results.length).toBeGreaterThan(0)
+			expect(results[0]!.items[0]!.type).toBe("weather")
+		})
+
+		test("stop unsubscribes from all sources", async () => {
+			const location = createLocationSource()
+
+			const engine = new FeedEngine().register(location)
+
+			let callCount = 0
+			engine.subscribe(() => {
+				callCount++
+			})
+
+			engine.start()
+			engine.stop()
+
+			// Simulate update after stop
+			location.simulateUpdate({ lat: 1, lng: 1 })
+
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(callCount).toBe(0)
+		})
+
+		test("start is idempotent", () => {
+			const location = createLocationSource()
+			const engine = new FeedEngine().register(location)
+
+			// Should not throw or double-subscribe
+			engine.start()
+			engine.start()
+			engine.stop()
+		})
+	})
+})

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

@@ -0,0 +1,335 @@
+import type { Context } from "./context"
+import type { FeedItem } from "./feed"
+import type { FeedSource } from "./feed-source"
+
+export interface SourceError {
+	sourceId: string
+	error: Error
+}
+
+export interface FeedResult<TItem extends FeedItem = FeedItem> {
+	context: Context
+	items: TItem[]
+	errors: SourceError[]
+}
+
+export type FeedSubscriber<TItem extends FeedItem = FeedItem> = (result: FeedResult<TItem>) => void
+
+interface SourceGraph {
+	sources: Map<string, FeedSource>
+	sorted: FeedSource[]
+	dependents: Map<string, string[]>
+}
+
+/**
+ * Orchestrates FeedSources, managing the dependency graph and context flow.
+ *
+ * Sources declare dependencies on other sources. The engine:
+ * - Validates the dependency graph (no missing deps, no cycles)
+ * - Runs fetchContext() in topological order during refresh
+ * - Runs fetchItems() on all sources with accumulated context
+ * - Subscribes to reactive updates via onContextUpdate/onItemsUpdate
+ *
+ * @example
+ * ```ts
+ * const engine = new FeedEngine()
+ *   .register(locationSource)
+ *   .register(weatherSource)
+ *   .register(alertSource)
+ *
+ * // Pull-based refresh
+ * const { context, items, errors } = await engine.refresh()
+ *
+ * // Reactive updates
+ * engine.subscribe((result) => {
+ *   console.log(result.items)
+ * })
+ * engine.start()
+ *
+ * // Cleanup
+ * engine.stop()
+ * ```
+ */
+export class FeedEngine<TItems extends FeedItem = FeedItem> {
+	private sources = new Map<string, FeedSource>()
+	private graph: SourceGraph | null = null
+	private context: Context = { time: new Date() }
+	private subscribers = new Set<FeedSubscriber<TItems>>()
+	private cleanups: Array<() => void> = []
+	private started = false
+
+	/**
+	 * Registers a FeedSource. Invalidates the cached graph.
+	 */
+	register<TItem extends FeedItem>(source: FeedSource<TItem>): FeedEngine<TItems | TItem> {
+		this.sources.set(source.id, source)
+		this.graph = null
+		return this as FeedEngine<TItems | TItem>
+	}
+
+	/**
+	 * Unregisters a FeedSource by ID. Invalidates the cached graph.
+	 */
+	unregister(sourceId: string): this {
+		this.sources.delete(sourceId)
+		this.graph = null
+		return this
+	}
+
+	/**
+	 * Refreshes the feed by running all sources in dependency order.
+	 * Calls fetchContext() then fetchItems() on each source.
+	 */
+	async refresh(): Promise<FeedResult<TItems>> {
+		const graph = this.ensureGraph()
+		const errors: SourceError[] = []
+
+		// Reset context with fresh time
+		let context: Context = { time: new Date() }
+
+		// Run fetchContext in topological order
+		for (const source of graph.sorted) {
+			if (source.fetchContext) {
+				try {
+					const update = await source.fetchContext(context)
+					context = { ...context, ...update }
+				} catch (err) {
+					errors.push({
+						sourceId: source.id,
+						error: err instanceof Error ? err : new Error(String(err)),
+					})
+				}
+			}
+		}
+
+		// Run fetchItems on all sources
+		const items: FeedItem[] = []
+		for (const source of graph.sorted) {
+			if (source.fetchItems) {
+				try {
+					const sourceItems = await source.fetchItems(context)
+					items.push(...sourceItems)
+				} catch (err) {
+					errors.push({
+						sourceId: source.id,
+						error: err instanceof Error ? err : new Error(String(err)),
+					})
+				}
+			}
+		}
+
+		// Sort by priority descending
+		items.sort((a, b) => b.priority - a.priority)
+
+		this.context = context
+
+		return { context, items: items as TItems[], errors }
+	}
+
+	/**
+	 * Subscribes to feed updates. Returns unsubscribe function.
+	 */
+	subscribe(callback: FeedSubscriber<TItems>): () => void {
+		this.subscribers.add(callback)
+		return () => {
+			this.subscribers.delete(callback)
+		}
+	}
+
+	/**
+	 * Starts reactive subscriptions on all sources.
+	 * Sources with onContextUpdate will trigger re-computation of dependents.
+	 */
+	start(): void {
+		if (this.started) return
+
+		this.started = true
+		const graph = this.ensureGraph()
+
+		for (const source of graph.sorted) {
+			if (source.onContextUpdate) {
+				const cleanup = source.onContextUpdate(
+					(update) => {
+						this.handleContextUpdate(source.id, update)
+					},
+					() => this.context,
+				)
+				this.cleanups.push(cleanup)
+			}
+
+			if (source.onItemsUpdate) {
+				const cleanup = source.onItemsUpdate(
+					() => {
+						this.scheduleRefresh()
+					},
+					() => this.context,
+				)
+				this.cleanups.push(cleanup)
+			}
+		}
+	}
+
+	/**
+	 * Stops all reactive subscriptions.
+	 */
+	stop(): void {
+		this.started = false
+		for (const cleanup of this.cleanups) {
+			cleanup()
+		}
+		this.cleanups = []
+	}
+
+	/**
+	 * Returns the current accumulated context.
+	 */
+	currentContext(): Context {
+		return this.context
+	}
+
+	private ensureGraph(): SourceGraph {
+		if (!this.graph) {
+			this.graph = buildGraph(Array.from(this.sources.values()))
+		}
+		return this.graph
+	}
+
+	private handleContextUpdate(sourceId: string, update: Partial<Context>): void {
+		this.context = { ...this.context, ...update, time: new Date() }
+
+		// Re-run dependents and notify
+		this.refreshDependents(sourceId)
+	}
+
+	private async refreshDependents(sourceId: string): Promise<void> {
+		const graph = this.ensureGraph()
+		const toRefresh = this.collectDependents(sourceId, graph)
+
+		// Re-run fetchContext for dependents in order
+		for (const id of toRefresh) {
+			const source = graph.sources.get(id)
+			if (source?.fetchContext) {
+				try {
+					const update = await source.fetchContext(this.context)
+					this.context = { ...this.context, ...update }
+				} catch {
+					// Errors during reactive updates are logged but don't stop propagation
+				}
+			}
+		}
+
+		// Collect items from all sources
+		const items: FeedItem[] = []
+		const errors: SourceError[] = []
+
+		for (const source of graph.sorted) {
+			if (source.fetchItems) {
+				try {
+					const sourceItems = await source.fetchItems(this.context)
+					items.push(...sourceItems)
+				} catch (err) {
+					errors.push({
+						sourceId: source.id,
+						error: err instanceof Error ? err : new Error(String(err)),
+					})
+				}
+			}
+		}
+
+		items.sort((a, b) => b.priority - a.priority)
+
+		this.notifySubscribers({ context: this.context, items: items as TItems[], errors })
+	}
+
+	private collectDependents(sourceId: string, graph: SourceGraph): string[] {
+		const result: string[] = []
+		const visited = new Set<string>()
+
+		const collect = (id: string): void => {
+			const deps = graph.dependents.get(id) ?? []
+			for (const dep of deps) {
+				if (!visited.has(dep)) {
+					visited.add(dep)
+					result.push(dep)
+					collect(dep)
+				}
+			}
+		}
+
+		collect(sourceId)
+
+		// Return in topological order
+		return graph.sorted.filter((s) => result.includes(s.id)).map((s) => s.id)
+	}
+
+	private scheduleRefresh(): void {
+		// Simple immediate refresh for now - could add debouncing later
+		this.refresh().then((result) => {
+			this.notifySubscribers(result)
+		})
+	}
+
+	private notifySubscribers(result: FeedResult<TItems>): void {
+		this.subscribers.forEach((callback) => {
+			try {
+				callback(result)
+			} catch {
+				// Subscriber errors shouldn't break other subscribers
+			}
+		})
+	}
+}
+
+function buildGraph(sources: FeedSource[]): SourceGraph {
+	const byId = new Map<string, FeedSource>()
+	for (const source of sources) {
+		byId.set(source.id, source)
+	}
+
+	// Validate dependencies exist
+	for (const source of sources) {
+		for (const dep of source.dependencies ?? []) {
+			if (!byId.has(dep)) {
+				throw new Error(`Source "${source.id}" depends on "${dep}" which is not registered`)
+			}
+		}
+	}
+
+	// Check for cycles and topologically sort
+	const visited = new Set<string>()
+	const visiting = new Set<string>()
+	const sorted: FeedSource[] = []
+
+	function visit(id: string, path: string[]): void {
+		if (visiting.has(id)) {
+			const cycle = [...path.slice(path.indexOf(id)), id].join(" → ")
+			throw new Error(`Circular dependency detected: ${cycle}`)
+		}
+		if (visited.has(id)) return
+
+		visiting.add(id)
+		const source = byId.get(id)!
+		for (const dep of source.dependencies ?? []) {
+			visit(dep, [...path, id])
+		}
+		visiting.delete(id)
+		visited.add(id)
+		sorted.push(source)
+	}
+
+	for (const source of sources) {
+		visit(source.id, [])
+	}
+
+	// Build reverse dependency map
+	const dependents = new Map<string, string[]>()
+	for (const source of sources) {
+		for (const dep of source.dependencies ?? []) {
+			const list = dependents.get(dep) ?? []
+			list.push(source.id)
+			dependents.set(dep, list)
+		}
+	}
+
+	return { sources: byId, sorted, dependents }
+}

packages/aris-core/src/index.ts

@@ -8,20 +8,35 @@ export type { FeedItem } from "./feed"
 // Feed Source
 export type { FeedSource } from "./feed-source"
 
+// Feed Engine
+export type { FeedResult, FeedSubscriber, SourceError } from "./feed-engine"
+export { FeedEngine } from "./feed-engine"
+
+// =============================================================================
+// DEPRECATED - Use FeedSource + FeedEngine instead
+// =============================================================================
+
 // Data Source (deprecated - use FeedSource)
 export type { DataSource } from "./data-source"
 
-// Context Provider
+// Context Provider (deprecated - use FeedSource)
 export type { ContextProvider } from "./context-provider"
 
-// Context Bridge
+// Context Bridge (deprecated - use FeedEngine)
 export type { ProviderError, RefreshResult } from "./context-bridge"
 export { ContextBridge } from "./context-bridge"
 
-// Reconciler
+// Reconciler (deprecated - use FeedEngine)
-export type { ReconcileResult, ReconcilerConfig, SourceError } from "./reconciler"
+export type {
+	ReconcileResult,
+	ReconcilerConfig,
+	SourceError as ReconcilerSourceError,
+} from "./reconciler"
 export { Reconciler } from "./reconciler"
 
-// Feed Controller
+// Feed Controller (deprecated - use FeedEngine)
-export type { FeedControllerConfig, FeedSubscriber } from "./feed-controller"
+export type {
+	FeedControllerConfig,
+	FeedSubscriber as FeedControllerSubscriber,
+} from "./feed-controller"
 export { FeedController } from "./feed-controller"

packages/aris-source-location/README.md

@@ -0,0 +1,112 @@
+# @aris/source-location
+
+A FeedSource that provides location context to the ARIS feed graph.
+
+## Overview
+
+This source accepts external location pushes and does not query location itself. It provides location context to downstream sources (e.g., weather, transit) but does not produce feed items.
+
+## Installation
+
+```bash
+bun add @aris/source-location
+```
+
+## Usage
+
+```ts
+import { LocationSource, LocationKey, type Location } from "@aris/source-location"
+import { contextValue } from "@aris/core"
+
+// Create source with default history size (1)
+const locationSource = new LocationSource()
+
+// Or keep last 10 locations
+const locationSource = new LocationSource({ historySize: 10 })
+
+// Push location from external provider (GPS, network, etc.)
+locationSource.pushLocation({
+	lat: 37.7749,
+	lng: -122.4194,
+	accuracy: 10,
+	timestamp: new Date(),
+})
+
+// Access current location
+locationSource.lastLocation // { lat, lng, accuracy, timestamp } | null
+
+// Access location history (oldest first)
+locationSource.locationHistory // readonly Location[]
+```
+
+### With FeedController
+
+```ts
+import { FeedController } from "@aris/core"
+import { LocationSource } from "@aris/source-location"
+
+const locationSource = new LocationSource()
+
+const controller = new FeedController({
+	sources: [locationSource, weatherSource, transitSource],
+})
+
+// Push location updates - downstream sources will re-fetch
+locationSource.pushLocation({
+	lat: 37.7749,
+	lng: -122.4194,
+	accuracy: 10,
+	timestamp: new Date(),
+})
+```
+
+### Reading Location in Downstream Sources
+
+```ts
+import { contextValue, type FeedSource } from "@aris/core"
+import { LocationKey } from "@aris/source-location"
+
+const weatherSource: FeedSource = {
+	id: "weather",
+	dependencies: ["location"],
+
+	async fetchContext(context) {
+		const location = contextValue(context, LocationKey)
+		if (!location) return {}
+
+		const weather = await fetchWeather(location.lat, location.lng)
+		return { [WeatherKey]: weather }
+	},
+}
+```
+
+## API
+
+### `LocationSource`
+
+| Member                   | Type                  | Description                           |
+| ------------------------ | --------------------- | ------------------------------------- |
+| `id`                     | `"location"`          | Source identifier                     |
+| `constructor(options?)`  |                       | Create with optional `historySize`    |
+| `pushLocation(location)` | `void`                | Push new location, notifies listeners |
+| `lastLocation`           | `Location \| null`    | Most recent location                  |
+| `locationHistory`        | `readonly Location[]` | All retained locations, oldest first  |
+
+### `Location`
+
+```ts
+interface Location {
+	lat: number
+	lng: number
+	accuracy: number // meters
+	timestamp: Date
+}
+```
+
+### `LocationKey`
+
+Typed context key for accessing location in downstream sources:
+
+```ts
+const location = contextValue(context, LocationKey)
+```

packages/aris-source-location/package.json

@@ -0,0 +1,13 @@
+{
+	"name": "@aris/source-location",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test src/"
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*"
+	}
+}

packages/aris-source-location/src/index.ts

@@ -0,0 +1,6 @@
+export {
+	LocationSource,
+	LocationKey,
+	type Location,
+	type LocationSourceOptions,
+} from "./location-source.ts"

packages/aris-source-location/src/location-source.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, mock, test } from "bun:test"
+
+import { LocationKey, LocationSource, type Location } from "./location-source.ts"
+
+function createLocation(overrides: Partial<Location> = {}): Location {
+	return {
+		lat: 37.7749,
+		lng: -122.4194,
+		accuracy: 10,
+		timestamp: new Date(),
+		...overrides,
+	}
+}
+
+describe("LocationSource", () => {
+	describe("FeedSource interface", () => {
+		test("has correct id", () => {
+			const source = new LocationSource()
+			expect(source.id).toBe("location")
+		})
+
+		test("fetchItems always returns empty array", async () => {
+			const source = new LocationSource()
+			source.pushLocation(createLocation())
+
+			const items = await source.fetchItems()
+			expect(items).toEqual([])
+		})
+
+		test("fetchContext returns empty when no location", async () => {
+			const source = new LocationSource()
+
+			const context = await source.fetchContext()
+			expect(context).toEqual({})
+		})
+
+		test("fetchContext returns location when available", async () => {
+			const source = new LocationSource()
+			const location = createLocation()
+			source.pushLocation(location)
+
+			const context = await source.fetchContext()
+			expect(context).toEqual({ [LocationKey]: location })
+		})
+	})
+
+	describe("pushLocation", () => {
+		test("updates lastLocation", () => {
+			const source = new LocationSource()
+			expect(source.lastLocation).toBeNull()
+
+			const location = createLocation()
+			source.pushLocation(location)
+
+			expect(source.lastLocation).toEqual(location)
+		})
+
+		test("notifies listeners", () => {
+			const source = new LocationSource()
+			const listener = mock()
+
+			source.onContextUpdate(listener)
+
+			const location = createLocation()
+			source.pushLocation(location)
+
+			expect(listener).toHaveBeenCalledTimes(1)
+			expect(listener).toHaveBeenCalledWith({ [LocationKey]: location })
+		})
+	})
+
+	describe("history", () => {
+		test("default historySize is 1", () => {
+			const source = new LocationSource()
+
+			source.pushLocation(createLocation({ lat: 1 }))
+			source.pushLocation(createLocation({ lat: 2 }))
+
+			expect(source.locationHistory).toHaveLength(1)
+			expect(source.lastLocation?.lat).toBe(2)
+		})
+
+		test("respects configured historySize", () => {
+			const source = new LocationSource({ historySize: 3 })
+
+			const loc1 = createLocation({ lat: 1 })
+			const loc2 = createLocation({ lat: 2 })
+			const loc3 = createLocation({ lat: 3 })
+
+			source.pushLocation(loc1)
+			source.pushLocation(loc2)
+			source.pushLocation(loc3)
+
+			expect(source.locationHistory).toEqual([loc1, loc2, loc3])
+		})
+
+		test("evicts oldest when exceeding historySize", () => {
+			const source = new LocationSource({ historySize: 2 })
+
+			const loc1 = createLocation({ lat: 1 })
+			const loc2 = createLocation({ lat: 2 })
+			const loc3 = createLocation({ lat: 3 })
+
+			source.pushLocation(loc1)
+			source.pushLocation(loc2)
+			source.pushLocation(loc3)
+
+			expect(source.locationHistory).toEqual([loc2, loc3])
+		})
+
+		test("locationHistory is readonly", () => {
+			const source = new LocationSource({ historySize: 3 })
+			source.pushLocation(createLocation())
+
+			const history = source.locationHistory
+			expect(Array.isArray(history)).toBe(true)
+		})
+	})
+
+	describe("onContextUpdate", () => {
+		test("returns cleanup function", () => {
+			const source = new LocationSource()
+			const listener = mock()
+
+			const cleanup = source.onContextUpdate(listener)
+
+			source.pushLocation(createLocation({ lat: 1 }))
+			expect(listener).toHaveBeenCalledTimes(1)
+
+			cleanup()
+
+			source.pushLocation(createLocation({ lat: 2 }))
+			expect(listener).toHaveBeenCalledTimes(1)
+		})
+
+		test("supports multiple listeners", () => {
+			const source = new LocationSource()
+			const listener1 = mock()
+			const listener2 = mock()
+
+			source.onContextUpdate(listener1)
+			source.onContextUpdate(listener2)
+
+			source.pushLocation(createLocation())
+
+			expect(listener1).toHaveBeenCalledTimes(1)
+			expect(listener2).toHaveBeenCalledTimes(1)
+		})
+	})
+})

packages/aris-source-location/src/location-source.ts

@@ -0,0 +1,86 @@
+import type { Context, FeedSource } from "@aris/core"
+
+import { contextKey, type ContextKey } from "@aris/core"
+
+/**
+ * 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
+}
+
+export const LocationKey: ContextKey<Location> = contextKey("location")
+
+/**
+ * A FeedSource that provides location context.
+ *
+ * This source accepts external location pushes and does not query location itself.
+ * Use `pushLocation` to update the location from an external provider (e.g., GPS, network).
+ *
+ * Does not produce feed items - always returns empty array from `fetchItems`.
+ */
+export class LocationSource implements FeedSource {
+	readonly id = "location"
+
+	private readonly historySize: number
+	private locations: Location[] = []
+	private listeners = new Set<(update: Partial<Context>) => void>()
+
+	constructor(options: LocationSourceOptions = {}) {
+		this.historySize = options.historySize ?? 1
+	}
+
+	/**
+	 * Push a new location update. Notifies all context listeners.
+	 */
+	pushLocation(location: Location): void {
+		this.locations.push(location)
+		if (this.locations.length > this.historySize) {
+			this.locations.shift()
+		}
+		this.listeners.forEach((listener) => {
+			listener({ [LocationKey]: location })
+		})
+	}
+
+	/**
+	 * Most recent location, or null if none pushed.
+	 */
+	get lastLocation(): Location | null {
+		return this.locations[this.locations.length - 1] ?? null
+	}
+
+	/**
+	 * Location history, oldest first. Length limited by `historySize`.
+	 */
+	get locationHistory(): readonly Location[] {
+		return this.locations
+	}
+
+	onContextUpdate(callback: (update: Partial<Context>) => void): () => void {
+		this.listeners.add(callback)
+		return () => {
+			this.listeners.delete(callback)
+		}
+	}
+
+	async fetchContext(): Promise<Partial<Context>> {
+		if (this.lastLocation) {
+			return { [LocationKey]: this.lastLocation }
+		}
+		return {}
+	}
+
+	async fetchItems(): Promise<[]> {
+		return []
+	}
+}

packages/aris-source-weatherkit/README.md

@@ -0,0 +1,101 @@
+# @aris/source-weatherkit
+
+Weather feed source using Apple WeatherKit API.
+
+## Usage
+
+### Basic Setup
+
+```ts
+import { WeatherSource, Units } from "@aris/source-weatherkit"
+
+const weatherSource = new WeatherSource({
+	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!,
+	},
+	units: Units.metric,
+})
+```
+
+### With Feed Source Graph
+
+```ts
+import { LocationSource } from "@aris/source-location"
+import { WeatherSource } from "@aris/source-weatherkit"
+
+const locationSource = new LocationSource()
+const weatherSource = new WeatherSource({ credentials })
+
+// Weather depends on location - graph handles ordering
+const sources = [locationSource, weatherSource]
+```
+
+### Reading Weather Context
+
+Downstream sources can access weather data:
+
+```ts
+import { contextValue } from "@aris/core"
+import { WeatherKey } from "@aris/source-weatherkit"
+
+async function fetchContext(context: Context) {
+	const weather = contextValue(context, WeatherKey)
+
+	if (weather?.condition === "Rain") {
+		// Suggest umbrella, indoor activities, etc.
+	}
+
+	if (weather && weather.uvIndex > 7) {
+		// Suggest sunscreen
+	}
+}
+```
+
+## Exports
+
+| Export          | Description                             |
+| --------------- | --------------------------------------- |
+| `WeatherSource` | FeedSource implementation               |
+| `WeatherKey`    | Context key for simplified weather data |
+| `Weather`       | Type for weather context                |
+| `Units`         | `metric` or `imperial`                  |
+
+## Options
+
+| Option        | Default  | Description                |
+| ------------- | -------- | -------------------------- |
+| `credentials` | -        | WeatherKit API credentials |
+| `client`      | -        | Custom WeatherKit client   |
+| `hourlyLimit` | `12`     | Max hourly forecasts       |
+| `dailyLimit`  | `7`      | Max daily forecasts        |
+| `units`       | `metric` | Temperature/speed units    |
+
+## Context
+
+Provides simplified weather context for downstream sources:
+
+```ts
+interface Weather {
+	temperature: number
+	temperatureApparent: number
+	condition: ConditionCode
+	humidity: number
+	uvIndex: number
+	windSpeed: number
+	daylight: boolean
+}
+```
+
+## Feed Items
+
+Produces feed items:
+
+- `weather-current` - Current conditions
+- `weather-hourly` - Hourly forecasts (up to `hourlyLimit`)
+- `weather-daily` - Daily forecasts (up to `dailyLimit`)
+- `weather-alert` - Weather alerts when present
+
+Priority is adjusted based on weather severity (storms, extreme temperatures).

packages/aris-source-weatherkit/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "@aris/source-weatherkit",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test ."
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*",
+		"@aris/source-location": "workspace:*",
+		"arktype": "^2.1.0"
+	}
+}

packages/aris-source-weatherkit/src/feed-items.ts

@@ -0,0 +1,97 @@
+import type { FeedItem } from "@aris/core"
+
+import type { Certainty, ConditionCode, PrecipitationType, Severity, Urgency } from "./weatherkit"
+
+export const WeatherFeedItemType = {
+	current: "weather-current",
+	hourly: "weather-hourly",
+	daily: "weather-daily",
+	alert: "weather-alert",
+} as const
+
+export type WeatherFeedItemType = (typeof WeatherFeedItemType)[keyof typeof WeatherFeedItemType]
+
+export type CurrentWeatherData = {
+	conditionCode: ConditionCode
+	daylight: boolean
+	humidity: number
+	precipitationIntensity: number
+	pressure: number
+	pressureTrend: "rising" | "falling" | "steady"
+	temperature: number
+	temperatureApparent: number
+	uvIndex: number
+	visibility: number
+	windDirection: number
+	windGust: number
+	windSpeed: number
+}
+
+export interface CurrentWeatherFeedItem extends FeedItem<
+	typeof WeatherFeedItemType.current,
+	CurrentWeatherData
+> {}
+
+export type HourlyWeatherData = {
+	forecastTime: Date
+	conditionCode: ConditionCode
+	daylight: boolean
+	humidity: number
+	precipitationAmount: number
+	precipitationChance: number
+	precipitationType: PrecipitationType
+	temperature: number
+	temperatureApparent: number
+	uvIndex: number
+	windDirection: number
+	windGust: number
+	windSpeed: number
+}
+
+export interface HourlyWeatherFeedItem extends FeedItem<
+	typeof WeatherFeedItemType.hourly,
+	HourlyWeatherData
+> {}
+
+export type DailyWeatherData = {
+	forecastDate: Date
+	conditionCode: ConditionCode
+	maxUvIndex: number
+	precipitationAmount: number
+	precipitationChance: number
+	precipitationType: PrecipitationType
+	snowfallAmount: number
+	sunrise: Date
+	sunset: Date
+	temperatureMax: number
+	temperatureMin: number
+}
+
+export interface DailyWeatherFeedItem extends FeedItem<
+	typeof WeatherFeedItemType.daily,
+	DailyWeatherData
+> {}
+
+export type WeatherAlertData = {
+	alertId: string
+	areaName: string
+	certainty: Certainty
+	description: string
+	detailsUrl: string
+	effectiveTime: Date
+	expireTime: Date
+	severity: Severity
+	source: string
+	urgency: Urgency
+}
+
+export interface WeatherAlertFeedItem extends FeedItem<
+	typeof WeatherFeedItemType.alert,
+	WeatherAlertData
+> {}
+
+export type WeatherFeedItem =
+	| CurrentWeatherFeedItem
+	| HourlyWeatherFeedItem
+	| DailyWeatherFeedItem
+	| WeatherAlertFeedItem

packages/aris-source-weatherkit/src/index.ts

@@ -0,0 +1,39 @@
+export { WeatherKey, type Weather } from "./weather-context"
+export {
+	WeatherSource,
+	Units,
+	type Units as UnitsType,
+	type WeatherSourceOptions,
+} from "./weather-source"
+
+export {
+	WeatherFeedItemType,
+	type WeatherFeedItemType as WeatherFeedItemTypeType,
+	type WeatherFeedItem,
+	type CurrentWeatherFeedItem,
+	type CurrentWeatherData,
+	type HourlyWeatherFeedItem,
+	type HourlyWeatherData,
+	type DailyWeatherFeedItem,
+	type DailyWeatherData,
+	type WeatherAlertFeedItem,
+	type WeatherAlertData,
+} from "./feed-items"
+
+export {
+	ConditionCode,
+	Severity,
+	Urgency,
+	Certainty,
+	PrecipitationType,
+	DefaultWeatherKitClient,
+	type ConditionCode as ConditionCodeType,
+	type Severity as SeverityType,
+	type Urgency as UrgencyType,
+	type Certainty as CertaintyType,
+	type PrecipitationType as PrecipitationTypeType,
+	type WeatherKitClient,
+	type WeatherKitCredentials,
+	type WeatherKitQueryOptions,
+	type WeatherKitResponse,
+} from "./weatherkit"

packages/aris-source-weatherkit/src/weather-context.ts

@@ -0,0 +1,27 @@
+import type { ContextKey } from "@aris/core"
+
+import { contextKey } from "@aris/core"
+
+import type { ConditionCode } from "./weatherkit"
+
+/**
+ * Simplified weather context for downstream sources.
+ */
+export interface Weather {
+	/** Current temperature */
+	temperature: number
+	/** Feels-like temperature */
+	temperatureApparent: number
+	/** Weather condition */
+	condition: ConditionCode
+	/** Relative humidity (0-1) */
+	humidity: number
+	/** UV index */
+	uvIndex: number
+	/** Wind speed */
+	windSpeed: number
+	/** Is it currently daytime */
+	daylight: boolean
+}
+
+export const WeatherKey: ContextKey<Weather> = contextKey("weather")

packages/aris-source-weatherkit/src/weather-source.test.ts

@@ -0,0 +1,182 @@
+import { contextValue, type Context } from "@aris/core"
+import { LocationKey } from "@aris/source-location"
+import { describe, expect, test } from "bun:test"
+
+import type { WeatherKitClient, WeatherKitResponse } from "./weatherkit"
+
+import fixture from "../fixtures/san-francisco.json"
+import { WeatherFeedItemType } from "./feed-items"
+import { WeatherKey } from "./weather-context"
+import { WeatherSource, Units } from "./weather-source"
+
+const mockCredentials = {
+	privateKey: "mock",
+	keyId: "mock",
+	teamId: "mock",
+	serviceId: "mock",
+}
+
+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("WeatherSource", () => {
+	describe("properties", () => {
+		test("has correct id", () => {
+			const source = new WeatherSource({ credentials: mockCredentials })
+			expect(source.id).toBe("weather")
+		})
+
+		test("depends on location", () => {
+			const source = new WeatherSource({ credentials: mockCredentials })
+			expect(source.dependencies).toEqual(["location"])
+		})
+
+		test("throws error if neither client nor credentials provided", () => {
+			expect(() => new WeatherSource({} as never)).toThrow(
+				"Either client or credentials must be provided",
+			)
+		})
+	})
+
+	describe("fetchContext", () => {
+		const mockClient = createMockClient(fixture.response as WeatherKitResponse)
+
+		test("returns empty when no location", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const result = await source.fetchContext(createMockContext())
+
+			expect(result).toEqual({})
+		})
+
+		test("returns simplified weather context", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const result = await source.fetchContext(context)
+			const weather = contextValue(result, WeatherKey)
+
+			expect(weather).toBeDefined()
+			expect(typeof weather!.temperature).toBe("number")
+			expect(typeof weather!.temperatureApparent).toBe("number")
+			expect(typeof weather!.condition).toBe("string")
+			expect(typeof weather!.humidity).toBe("number")
+			expect(typeof weather!.uvIndex).toBe("number")
+			expect(typeof weather!.windSpeed).toBe("number")
+			expect(typeof weather!.daylight).toBe("boolean")
+		})
+
+		test("converts temperature to imperial", async () => {
+			const source = new WeatherSource({ client: mockClient, units: Units.imperial })
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const result = await source.fetchContext(context)
+			const weather = contextValue(result, WeatherKey)
+
+			// Fixture has temperature around 10°C, imperial should be around 50°F
+			expect(weather!.temperature).toBeGreaterThan(40)
+		})
+	})
+
+	describe("fetchItems", () => {
+		const mockClient = createMockClient(fixture.response as WeatherKitResponse)
+
+		test("returns empty array when no location", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const items = await source.fetchItems(createMockContext())
+
+			expect(items).toEqual([])
+		})
+
+		test("returns feed items with all types", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const items = await source.fetchItems(context)
+
+			expect(items.length).toBeGreaterThan(0)
+			expect(items.some((i) => i.type === WeatherFeedItemType.current)).toBe(true)
+			expect(items.some((i) => i.type === WeatherFeedItemType.hourly)).toBe(true)
+			expect(items.some((i) => i.type === WeatherFeedItemType.daily)).toBe(true)
+		})
+
+		test("applies hourly and daily limits", async () => {
+			const source = new WeatherSource({
+				client: mockClient,
+				hourlyLimit: 3,
+				dailyLimit: 2,
+			})
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const items = await source.fetchItems(context)
+
+			const hourlyItems = items.filter((i) => i.type === WeatherFeedItemType.hourly)
+			const dailyItems = items.filter((i) => i.type === WeatherFeedItemType.daily)
+
+			expect(hourlyItems.length).toBe(3)
+			expect(dailyItems.length).toBe(2)
+		})
+
+		test("sets timestamp from context.time", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const queryTime = new Date("2026-01-17T12:00:00Z")
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+			context.time = queryTime
+
+			const items = await source.fetchItems(context)
+
+			for (const item of items) {
+				expect(item.timestamp).toEqual(queryTime)
+			}
+		})
+
+		test("assigns priority based on weather conditions", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const items = await source.fetchItems(context)
+
+			for (const item of items) {
+				expect(item.priority).toBeGreaterThanOrEqual(0)
+				expect(item.priority).toBeLessThanOrEqual(1)
+			}
+
+			const currentItem = items.find((i) => i.type === WeatherFeedItemType.current)
+			expect(currentItem).toBeDefined()
+			expect(currentItem!.priority).toBeGreaterThanOrEqual(0.5)
+		})
+
+		test("generates unique IDs for each item", async () => {
+			const source = new WeatherSource({ client: mockClient })
+			const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
+
+			const items = await source.fetchItems(context)
+			const ids = items.map((i) => i.id)
+			const uniqueIds = new Set(ids)
+
+			expect(uniqueIds.size).toBe(ids.length)
+		})
+	})
+
+	describe("no reactive methods", () => {
+		test("does not implement onContextUpdate", () => {
+			const source = new WeatherSource({ credentials: mockCredentials })
+			expect(source.onContextUpdate).toBeUndefined()
+		})
+
+		test("does not implement onItemsUpdate", () => {
+			const source = new WeatherSource({ credentials: mockCredentials })
+			expect(source.onItemsUpdate).toBeUndefined()
+		})
+	})
+})

packages/aris-source-weatherkit/src/weather-source.ts

@@ -0,0 +1,363 @@
+import type { Context, FeedSource } from "@aris/core"
+
+import { contextValue } from "@aris/core"
+import { LocationKey } from "@aris/source-location"
+
+import { WeatherFeedItemType, type WeatherFeedItem } from "./feed-items"
+import { WeatherKey, type Weather } from "./weather-context"
+import {
+	DefaultWeatherKitClient,
+	type ConditionCode,
+	type CurrentWeather,
+	type DailyForecast,
+	type HourlyForecast,
+	type Severity,
+	type WeatherAlert,
+	type WeatherKitClient,
+	type WeatherKitCredentials,
+} from "./weatherkit"
+
+export const Units = {
+	metric: "metric",
+	imperial: "imperial",
+} as const
+
+export type Units = (typeof Units)[keyof typeof Units]
+
+export interface WeatherSourceOptions {
+	credentials?: WeatherKitCredentials
+	client?: WeatherKitClient
+	/** Number of hourly forecasts to include (default: 12) */
+	hourlyLimit?: number
+	/** Number of daily forecasts to include (default: 7) */
+	dailyLimit?: number
+	/** Units for temperature and measurements (default: metric) */
+	units?: Units
+}
+
+const DEFAULT_HOURLY_LIMIT = 12
+const DEFAULT_DAILY_LIMIT = 7
+
+const BASE_PRIORITY = {
+	current: 0.5,
+	hourly: 0.3,
+	daily: 0.2,
+	alert: 0.7,
+} as const
+
+const SEVERE_CONDITIONS = new Set<ConditionCode>([
+	"SevereThunderstorm",
+	"Hurricane",
+	"Tornado",
+	"TropicalStorm",
+	"Blizzard",
+	"FreezingRain",
+	"Hail",
+	"Frigid",
+	"Hot",
+])
+
+const MODERATE_CONDITIONS = new Set<ConditionCode>([
+	"Thunderstorm",
+	"IsolatedThunderstorms",
+	"ScatteredThunderstorms",
+	"HeavyRain",
+	"HeavySnow",
+	"FreezingDrizzle",
+	"BlowingSnow",
+])
+
+/**
+ * A FeedSource that provides weather context and feed items using Apple WeatherKit.
+ *
+ * Depends on location source for coordinates. Provides simplified weather context
+ * for downstream sources and produces weather feed items (current, hourly, daily, alerts).
+ *
+ * @example
+ * ```ts
+ * const weatherSource = new WeatherSource({
+ *   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!,
+ *   },
+ *   units: Units.metric,
+ * })
+ *
+ * // Access weather context in downstream sources
+ * const weather = contextValue(context, WeatherKey)
+ * if (weather?.condition === "Rain") {
+ *   // suggest umbrella
+ * }
+ * ```
+ */
+export class WeatherSource implements FeedSource<WeatherFeedItem> {
+	readonly id = "weather"
+	readonly dependencies = ["location"]
+
+	private readonly client: WeatherKitClient
+	private readonly hourlyLimit: number
+	private readonly dailyLimit: number
+	private readonly units: Units
+
+	constructor(options: WeatherSourceOptions) {
+		if (!options.client && !options.credentials) {
+			throw new Error("Either client or credentials must be provided")
+		}
+		this.client = options.client ?? new DefaultWeatherKitClient(options.credentials!)
+		this.hourlyLimit = options.hourlyLimit ?? DEFAULT_HOURLY_LIMIT
+		this.dailyLimit = options.dailyLimit ?? DEFAULT_DAILY_LIMIT
+		this.units = options.units ?? Units.metric
+	}
+
+	async fetchContext(context: Context): Promise<Partial<Context>> {
+		const location = contextValue(context, LocationKey)
+		if (!location) {
+			return {}
+		}
+
+		const response = await this.client.fetch({
+			lat: location.lat,
+			lng: location.lng,
+		})
+
+		if (!response.currentWeather) {
+			return {}
+		}
+
+		const weather: Weather = {
+			temperature: convertTemperature(response.currentWeather.temperature, this.units),
+			temperatureApparent: convertTemperature(
+				response.currentWeather.temperatureApparent,
+				this.units,
+			),
+			condition: response.currentWeather.conditionCode,
+			humidity: response.currentWeather.humidity,
+			uvIndex: response.currentWeather.uvIndex,
+			windSpeed: convertSpeed(response.currentWeather.windSpeed, this.units),
+			daylight: response.currentWeather.daylight,
+		}
+
+		return { [WeatherKey]: weather }
+	}
+
+	async fetchItems(context: Context): Promise<WeatherFeedItem[]> {
+		const location = contextValue(context, LocationKey)
+		if (!location) {
+			return []
+		}
+
+		const timestamp = context.time
+
+		const response = await this.client.fetch({
+			lat: location.lat,
+			lng: location.lng,
+		})
+
+		const items: WeatherFeedItem[] = []
+
+		if (response.currentWeather) {
+			items.push(createCurrentWeatherFeedItem(response.currentWeather, timestamp, this.units))
+		}
+
+		if (response.forecastHourly?.hours) {
+			const hours = response.forecastHourly.hours.slice(0, this.hourlyLimit)
+			for (let i = 0; i < hours.length; i++) {
+				const hour = hours[i]
+				if (hour) {
+					items.push(createHourlyWeatherFeedItem(hour, i, timestamp, this.units))
+				}
+			}
+		}
+
+		if (response.forecastDaily?.days) {
+			const days = response.forecastDaily.days.slice(0, this.dailyLimit)
+			for (let i = 0; i < days.length; i++) {
+				const day = days[i]
+				if (day) {
+					items.push(createDailyWeatherFeedItem(day, i, timestamp, this.units))
+				}
+			}
+		}
+
+		if (response.weatherAlerts?.alerts) {
+			for (const alert of response.weatherAlerts.alerts) {
+				items.push(createWeatherAlertFeedItem(alert, timestamp))
+			}
+		}
+
+		return items
+	}
+}
+
+function adjustPriorityForCondition(basePriority: number, conditionCode: ConditionCode): number {
+	if (SEVERE_CONDITIONS.has(conditionCode)) {
+		return Math.min(1, basePriority + 0.3)
+	}
+	if (MODERATE_CONDITIONS.has(conditionCode)) {
+		return Math.min(1, basePriority + 0.15)
+	}
+	return basePriority
+}
+
+function adjustPriorityForAlertSeverity(severity: Severity): number {
+	switch (severity) {
+		case "extreme":
+			return 1
+		case "severe":
+			return 0.9
+		case "moderate":
+			return 0.75
+		case "minor":
+			return BASE_PRIORITY.alert
+	}
+}
+
+function convertTemperature(celsius: number, units: Units): number {
+	if (units === Units.imperial) {
+		return (celsius * 9) / 5 + 32
+	}
+	return celsius
+}
+
+function convertSpeed(kmh: number, units: Units): number {
+	if (units === Units.imperial) {
+		return kmh * 0.621371
+	}
+	return kmh
+}
+
+function convertDistance(km: number, units: Units): number {
+	if (units === Units.imperial) {
+		return km * 0.621371
+	}
+	return km
+}
+
+function convertPrecipitation(mm: number, units: Units): number {
+	if (units === Units.imperial) {
+		return mm * 0.0393701
+	}
+	return mm
+}
+
+function convertPressure(mb: number, units: Units): number {
+	if (units === Units.imperial) {
+		return mb * 0.02953
+	}
+	return mb
+}
+
+function createCurrentWeatherFeedItem(
+	current: CurrentWeather,
+	timestamp: Date,
+	units: Units,
+): WeatherFeedItem {
+	const priority = adjustPriorityForCondition(BASE_PRIORITY.current, current.conditionCode)
+
+	return {
+		id: `weather-current-${timestamp.getTime()}`,
+		type: WeatherFeedItemType.current,
+		priority,
+		timestamp,
+		data: {
+			conditionCode: current.conditionCode,
+			daylight: current.daylight,
+			humidity: current.humidity,
+			precipitationIntensity: convertPrecipitation(current.precipitationIntensity, units),
+			pressure: convertPressure(current.pressure, units),
+			pressureTrend: current.pressureTrend,
+			temperature: convertTemperature(current.temperature, units),
+			temperatureApparent: convertTemperature(current.temperatureApparent, units),
+			uvIndex: current.uvIndex,
+			visibility: convertDistance(current.visibility, units),
+			windDirection: current.windDirection,
+			windGust: convertSpeed(current.windGust, units),
+			windSpeed: convertSpeed(current.windSpeed, units),
+		},
+	}
+}
+
+function createHourlyWeatherFeedItem(
+	hourly: HourlyForecast,
+	index: number,
+	timestamp: Date,
+	units: Units,
+): WeatherFeedItem {
+	const priority = adjustPriorityForCondition(BASE_PRIORITY.hourly, hourly.conditionCode)
+
+	return {
+		id: `weather-hourly-${timestamp.getTime()}-${index}`,
+		type: WeatherFeedItemType.hourly,
+		priority,
+		timestamp,
+		data: {
+			forecastTime: new Date(hourly.forecastStart),
+			conditionCode: hourly.conditionCode,
+			daylight: hourly.daylight,
+			humidity: hourly.humidity,
+			precipitationAmount: convertPrecipitation(hourly.precipitationAmount, units),
+			precipitationChance: hourly.precipitationChance,
+			precipitationType: hourly.precipitationType,
+			temperature: convertTemperature(hourly.temperature, units),
+			temperatureApparent: convertTemperature(hourly.temperatureApparent, units),
+			uvIndex: hourly.uvIndex,
+			windDirection: hourly.windDirection,
+			windGust: convertSpeed(hourly.windGust, units),
+			windSpeed: convertSpeed(hourly.windSpeed, units),
+		},
+	}
+}
+
+function createDailyWeatherFeedItem(
+	daily: DailyForecast,
+	index: number,
+	timestamp: Date,
+	units: Units,
+): WeatherFeedItem {
+	const priority = adjustPriorityForCondition(BASE_PRIORITY.daily, daily.conditionCode)
+
+	return {
+		id: `weather-daily-${timestamp.getTime()}-${index}`,
+		type: WeatherFeedItemType.daily,
+		priority,
+		timestamp,
+		data: {
+			forecastDate: new Date(daily.forecastStart),
+			conditionCode: daily.conditionCode,
+			maxUvIndex: daily.maxUvIndex,
+			precipitationAmount: convertPrecipitation(daily.precipitationAmount, units),
+			precipitationChance: daily.precipitationChance,
+			precipitationType: daily.precipitationType,
+			snowfallAmount: convertPrecipitation(daily.snowfallAmount, units),
+			sunrise: new Date(daily.sunrise),
+			sunset: new Date(daily.sunset),
+			temperatureMax: convertTemperature(daily.temperatureMax, units),
+			temperatureMin: convertTemperature(daily.temperatureMin, units),
+		},
+	}
+}
+
+function createWeatherAlertFeedItem(alert: WeatherAlert, timestamp: Date): WeatherFeedItem {
+	const priority = adjustPriorityForAlertSeverity(alert.severity)
+
+	return {
+		id: `weather-alert-${alert.id}`,
+		type: WeatherFeedItemType.alert,
+		priority,
+		timestamp,
+		data: {
+			alertId: alert.id,
+			areaName: alert.areaName,
+			certainty: alert.certainty,
+			description: alert.description,
+			detailsUrl: alert.detailsUrl,
+			effectiveTime: new Date(alert.effectiveTime),
+			expireTime: new Date(alert.expireTime),
+			severity: alert.severity,
+			source: alert.source,
+			urgency: alert.urgency,
+		},
+	}
+}

packages/aris-source-weatherkit/src/weatherkit.ts

@@ -0,0 +1,367 @@
+// WeatherKit REST API client and response types
+// https://developer.apple.com/documentation/weatherkitrestapi
+
+import { type } from "arktype"
+
+export interface WeatherKitCredentials {
+	privateKey: string
+	keyId: string
+	teamId: string
+	serviceId: string
+}
+
+export interface WeatherKitQueryOptions {
+	lat: number
+	lng: number
+	language?: string
+	timezone?: string
+}
+
+export interface WeatherKitClient {
+	fetch(query: WeatherKitQueryOptions): Promise<WeatherKitResponse>
+}
+
+export class DefaultWeatherKitClient implements WeatherKitClient {
+	private readonly credentials: WeatherKitCredentials
+
+	constructor(credentials: WeatherKitCredentials) {
+		this.credentials = credentials
+	}
+
+	async fetch(query: WeatherKitQueryOptions): Promise<WeatherKitResponse> {
+		const token = await generateJwt(this.credentials)
+
+		const dataSets = ["currentWeather", "forecastHourly", "forecastDaily", "weatherAlerts"].join(
+			",",
+		)
+
+		const url = new URL(
+			`${WEATHERKIT_API_BASE}/weather/${query.language ?? "en"}/${query.lat}/${query.lng}`,
+		)
+		url.searchParams.set("dataSets", dataSets)
+		if (query.timezone) {
+			url.searchParams.set("timezone", query.timezone)
+		}
+
+		const response = await fetch(url.toString(), {
+			headers: {
+				Authorization: `Bearer ${token}`,
+			},
+		})
+
+		if (!response.ok) {
+			const body = await response.text()
+			throw new Error(`WeatherKit API error: ${response.status} ${response.statusText}: ${body}`)
+		}
+
+		const json = await response.json()
+		const result = weatherKitResponseSchema(json)
+
+		if (result instanceof type.errors) {
+			throw new Error(`WeatherKit API response validation failed: ${result.summary}`)
+		}
+
+		return result
+	}
+}
+
+export const Severity = {
+	Minor: "minor",
+	Moderate: "moderate",
+	Severe: "severe",
+	Extreme: "extreme",
+} as const
+
+export type Severity = (typeof Severity)[keyof typeof Severity]
+
+export const Urgency = {
+	Immediate: "immediate",
+	Expected: "expected",
+	Future: "future",
+	Past: "past",
+	Unknown: "unknown",
+} as const
+
+export type Urgency = (typeof Urgency)[keyof typeof Urgency]
+
+export const Certainty = {
+	Observed: "observed",
+	Likely: "likely",
+	Possible: "possible",
+	Unlikely: "unlikely",
+	Unknown: "unknown",
+} as const
+
+export type Certainty = (typeof Certainty)[keyof typeof Certainty]
+
+export const PrecipitationType = {
+	Clear: "clear",
+	Precipitation: "precipitation",
+	Rain: "rain",
+	Snow: "snow",
+	Sleet: "sleet",
+	Hail: "hail",
+	Mixed: "mixed",
+} as const
+
+export type PrecipitationType = (typeof PrecipitationType)[keyof typeof PrecipitationType]
+
+export const ConditionCode = {
+	Clear: "Clear",
+	Cloudy: "Cloudy",
+	Dust: "Dust",
+	Fog: "Fog",
+	Haze: "Haze",
+	MostlyClear: "MostlyClear",
+	MostlyCloudy: "MostlyCloudy",
+	PartlyCloudy: "PartlyCloudy",
+	ScatteredThunderstorms: "ScatteredThunderstorms",
+	Smoke: "Smoke",
+	Breezy: "Breezy",
+	Windy: "Windy",
+	Drizzle: "Drizzle",
+	HeavyRain: "HeavyRain",
+	Rain: "Rain",
+	Showers: "Showers",
+	Flurries: "Flurries",
+	HeavySnow: "HeavySnow",
+	MixedRainAndSleet: "MixedRainAndSleet",
+	MixedRainAndSnow: "MixedRainAndSnow",
+	MixedRainfall: "MixedRainfall",
+	MixedSnowAndSleet: "MixedSnowAndSleet",
+	ScatteredShowers: "ScatteredShowers",
+	ScatteredSnowShowers: "ScatteredSnowShowers",
+	Sleet: "Sleet",
+	Snow: "Snow",
+	SnowShowers: "SnowShowers",
+	Blizzard: "Blizzard",
+	BlowingSnow: "BlowingSnow",
+	FreezingDrizzle: "FreezingDrizzle",
+	FreezingRain: "FreezingRain",
+	Frigid: "Frigid",
+	Hail: "Hail",
+	Hot: "Hot",
+	Hurricane: "Hurricane",
+	IsolatedThunderstorms: "IsolatedThunderstorms",
+	SevereThunderstorm: "SevereThunderstorm",
+	Thunderstorm: "Thunderstorm",
+	Tornado: "Tornado",
+	TropicalStorm: "TropicalStorm",
+} as const
+
+export type ConditionCode = (typeof ConditionCode)[keyof typeof ConditionCode]
+
+const WEATHERKIT_API_BASE = "https://weatherkit.apple.com/api/v1"
+
+const severitySchema = type.enumerated(
+	Severity.Minor,
+	Severity.Moderate,
+	Severity.Severe,
+	Severity.Extreme,
+)
+
+const urgencySchema = type.enumerated(
+	Urgency.Immediate,
+	Urgency.Expected,
+	Urgency.Future,
+	Urgency.Past,
+	Urgency.Unknown,
+)
+
+const certaintySchema = type.enumerated(
+	Certainty.Observed,
+	Certainty.Likely,
+	Certainty.Possible,
+	Certainty.Unlikely,
+	Certainty.Unknown,
+)
+
+const precipitationTypeSchema = type.enumerated(
+	PrecipitationType.Clear,
+	PrecipitationType.Precipitation,
+	PrecipitationType.Rain,
+	PrecipitationType.Snow,
+	PrecipitationType.Sleet,
+	PrecipitationType.Hail,
+	PrecipitationType.Mixed,
+)
+
+const conditionCodeSchema = type.enumerated(...Object.values(ConditionCode))
+
+const pressureTrendSchema = type.enumerated("rising", "falling", "steady")
+
+const currentWeatherSchema = type({
+	asOf: "string",
+	conditionCode: conditionCodeSchema,
+	daylight: "boolean",
+	humidity: "number",
+	precipitationIntensity: "number",
+	pressure: "number",
+	pressureTrend: pressureTrendSchema,
+	temperature: "number",
+	temperatureApparent: "number",
+	temperatureDewPoint: "number",
+	uvIndex: "number",
+	visibility: "number",
+	windDirection: "number",
+	windGust: "number",
+	windSpeed: "number",
+})
+
+export type CurrentWeather = typeof currentWeatherSchema.infer
+
+const hourlyForecastSchema = type({
+	forecastStart: "string",
+	conditionCode: conditionCodeSchema,
+	daylight: "boolean",
+	humidity: "number",
+	precipitationAmount: "number",
+	precipitationChance: "number",
+	precipitationType: precipitationTypeSchema,
+	pressure: "number",
+	snowfallIntensity: "number",
+	temperature: "number",
+	temperatureApparent: "number",
+	temperatureDewPoint: "number",
+	uvIndex: "number",
+	visibility: "number",
+	windDirection: "number",
+	windGust: "number",
+	windSpeed: "number",
+})
+
+export type HourlyForecast = typeof hourlyForecastSchema.infer
+
+const dayWeatherConditionsSchema = type({
+	conditionCode: conditionCodeSchema,
+	humidity: "number",
+	precipitationAmount: "number",
+	precipitationChance: "number",
+	precipitationType: precipitationTypeSchema,
+	snowfallAmount: "number",
+	temperatureMax: "number",
+	temperatureMin: "number",
+	windDirection: "number",
+	"windGust?": "number",
+	windSpeed: "number",
+})
+
+export type DayWeatherConditions = typeof dayWeatherConditionsSchema.infer
+
+const dailyForecastSchema = type({
+	forecastStart: "string",
+	forecastEnd: "string",
+	conditionCode: conditionCodeSchema,
+	maxUvIndex: "number",
+	moonPhase: "string",
+	"moonrise?": "string",
+	"moonset?": "string",
+	precipitationAmount: "number",
+	precipitationChance: "number",
+	precipitationType: precipitationTypeSchema,
+	snowfallAmount: "number",
+	sunrise: "string",
+	sunriseCivil: "string",
+	sunriseNautical: "string",
+	sunriseAstronomical: "string",
+	sunset: "string",
+	sunsetCivil: "string",
+	sunsetNautical: "string",
+	sunsetAstronomical: "string",
+	temperatureMax: "number",
+	temperatureMin: "number",
+	"daytimeForecast?": dayWeatherConditionsSchema,
+	"overnightForecast?": dayWeatherConditionsSchema,
+})
+
+export type DailyForecast = typeof dailyForecastSchema.infer
+
+const weatherAlertSchema = type({
+	id: "string",
+	areaId: "string",
+	areaName: "string",
+	certainty: certaintySchema,
+	countryCode: "string",
+	description: "string",
+	detailsUrl: "string",
+	effectiveTime: "string",
+	expireTime: "string",
+	issuedTime: "string",
+	responses: "string[]",
+	severity: severitySchema,
+	source: "string",
+	urgency: urgencySchema,
+})
+
+export type WeatherAlert = typeof weatherAlertSchema.infer
+
+const weatherKitResponseSchema = type({
+	"currentWeather?": currentWeatherSchema,
+	"forecastHourly?": type({
+		hours: hourlyForecastSchema.array(),
+	}),
+	"forecastDaily?": type({
+		days: dailyForecastSchema.array(),
+	}),
+	"weatherAlerts?": type({
+		alerts: weatherAlertSchema.array(),
+	}),
+})
+
+export type WeatherKitResponse = typeof weatherKitResponseSchema.infer
+
+async function generateJwt(credentials: WeatherKitCredentials): Promise<string> {
+	const header = {
+		alg: "ES256",
+		kid: credentials.keyId,
+		id: `${credentials.teamId}.${credentials.serviceId}`,
+	}
+
+	const now = Math.floor(Date.now() / 1000)
+	const payload = {
+		iss: credentials.teamId,
+		iat: now,
+		exp: now + 3600,
+		sub: credentials.serviceId,
+	}
+
+	const encoder = new TextEncoder()
+	const headerB64 = btoa(JSON.stringify(header))
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "")
+	const payloadB64 = btoa(JSON.stringify(payload))
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "")
+
+	const signingInput = `${headerB64}.${payloadB64}`
+
+	const pemContents = credentials.privateKey
+		.replace(/-----BEGIN PRIVATE KEY-----/, "")
+		.replace(/-----END PRIVATE KEY-----/, "")
+		.replace(/\s/g, "")
+
+	const binaryKey = Uint8Array.from(atob(pemContents), (c) => c.charCodeAt(0))
+
+	const cryptoKey = await crypto.subtle.importKey(
+		"pkcs8",
+		binaryKey,
+		{ name: "ECDSA", namedCurve: "P-256" },
+		false,
+		["sign"],
+	)
+
+	const signature = await crypto.subtle.sign(
+		{ name: "ECDSA", hash: "SHA-256" },
+		cryptoKey,
+		encoder.encode(signingInput),
+	)
+
+	const signatureB64 = btoa(String.fromCharCode(...new Uint8Array(signature)))
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "")
+
+	return `${signingInput}.${signatureB64}`
+}