fix(core): correct main and types paths in package.json

Paths pointed to index.ts but actual file is at src/index.ts.

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

AGENTS.md

@@ -39,3 +39,4 @@ Use Bun exclusively. Do not use npm or yarn.
 
 - Branch: `feat/<task>`, `fix/<task>`, `ci/<task>`, etc.
 - Commits: conventional commit format, title <= 50 chars
+- Signing: If `GPG_PRIVATE_KEY_PASSPHRASE` env var is available, use it to sign commits with `git commit -S`

packages/aris-core/README.md

@@ -0,0 +1,186 @@
+# @aris/core
+
+Core orchestration layer for ARIS feed reconciliation.
+
+## Overview
+
+```mermaid
+flowchart TB
+    subgraph Sources["Feed Sources (Graph)"]
+        LS[Location Source]
+        WS[Weather Source]
+        TS[TFL Source]
+        CS[Calendar Source]
+    end
+
+    LS --> WS
+    LS --> TS
+
+    subgraph Controller["FeedController"]
+        direction TB
+        C1[Holds context]
+        C2[Manages source graph]
+        C3[Reconciles on update]
+        C4[Notifies subscribers]
+    end
+
+    Sources --> Controller
+    Controller --> Sub[Subscribers]
+```
+
+## Concepts
+
+### FeedSource
+
+A unified interface for sources that provide context and/or feed items. Sources form a dependency graph.
+
+```ts
+interface FeedSource<TItem extends FeedItem = FeedItem> {
+	readonly id: string
+	readonly dependencies?: readonly string[]
+
+	// Context production (optional)
+	onContextUpdate?(
+		callback: (update: Partial<Context>) => void,
+		getContext: () => Context,
+	): () => void
+	fetchContext?(context: Context): Promise<Partial<Context>>
+
+	// Feed item production (optional)
+	onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void
+	fetchItems?(context: Context): Promise<TItem[]>
+}
+```
+
+A source may:
+
+- Provide context for other sources (implement `fetchContext`/`onContextUpdate`)
+- Produce feed items (implement `fetchItems`/`onItemsUpdate`)
+- Both
+
+### Context Keys
+
+Each package exports typed context keys for type-safe access:
+
+```ts
+import { contextKey, type ContextKey } from "@aris/core"
+
+interface Location {
+	lat: number
+	lng: number
+}
+
+export const LocationKey: ContextKey<Location> = contextKey("location")
+```
+
+## Usage
+
+### Define a Context-Only Source
+
+```ts
+import type { FeedSource } from "@aris/core"
+
+const locationSource: FeedSource = {
+	id: "location",
+
+	onContextUpdate(callback, _getContext) {
+		const watchId = navigator.geolocation.watchPosition((pos) => {
+			callback({
+				[LocationKey]: { lat: pos.coords.latitude, lng: pos.coords.longitude },
+			})
+		})
+		return () => navigator.geolocation.clearWatch(watchId)
+	},
+
+	async fetchContext() {
+		const pos = await getCurrentPosition()
+		return {
+			[LocationKey]: { lat: pos.coords.latitude, lng: pos.coords.longitude },
+		}
+	},
+}
+```
+
+### Define a Source with Dependencies
+
+```ts
+import type { FeedSource, FeedItem } from "@aris/core"
+import { contextValue } from "@aris/core"
+
+type WeatherItem = FeedItem<"weather", { temp: number; condition: string }>
+
+const weatherSource: FeedSource<WeatherItem> = {
+	id: "weather",
+	dependencies: ["location"],
+
+	async fetchContext(context) {
+		const location = contextValue(context, LocationKey)
+		if (!location) return {}
+
+		const weather = await fetchWeatherApi(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: { temp: weather.temp, condition: weather.condition },
+			},
+		]
+	},
+}
+```
+
+### Graph Behavior
+
+The source graph:
+
+1. Validates all dependencies exist
+2. Detects circular dependencies
+3. Topologically sorts sources
+
+On refresh:
+
+1. `fetchContext` runs in dependency order
+2. `fetchItems` runs on all sources
+3. Combined items returned to subscribers
+
+On reactive update:
+
+1. Source pushes context update via `onContextUpdate` callback
+2. Dependent sources re-run `fetchContext`
+3. Affected sources re-run `fetchItems`
+4. Subscribers notified
+
+## API
+
+### Context
+
+| Export                       | Description                             |
+| ---------------------------- | --------------------------------------- |
+| `ContextKey<T>`              | Branded type for type-safe context keys |
+| `contextKey<T>(key)`         | Creates a typed context key             |
+| `contextValue(context, key)` | Type-safe context value accessor        |
+| `Context`                    | Time + arbitrary key-value bag          |
+
+### Feed
+
+| Export                   | Description              |
+| ------------------------ | ------------------------ |
+| `FeedSource<TItem>`      | Unified source interface |
+| `FeedItem<TType, TData>` | Single item in the feed  |
+
+### Legacy (deprecated)
+
+| Export                       | Description              |
+| ---------------------------- | ------------------------ |
+| `DataSource<TItem, TConfig>` | Use `FeedSource` instead |
+| `ContextProvider<T>`         | Use `FeedSource` instead |
+| `ContextBridge`              | Use source graph instead |

packages/aris-core/context.ts

@@ -1,10 +0,0 @@
-export interface Location {
-	lat: number
-	lng: number
-	accuracy: number
-}
-
-export interface Context {
-	time: Date
-	location?: Location
-}

packages/aris-core/data-source.ts

@@ -1,7 +0,0 @@
-import type { Context } from "./context"
-import type { FeedItem } from "./feed"
-
-export interface DataSource<TItem extends FeedItem = FeedItem, TConfig = unknown> {
-	readonly type: TItem["type"]
-	query(context: Context, config: TConfig): Promise<TItem[]>
-}

packages/aris-core/feed.ts

@@ -1,10 +0,0 @@
-export interface FeedItem<
-	TType extends string = string,
-	TData extends Record<string, unknown> = Record<string, unknown>,
-> {
-	id: string
-	type: TType
-	priority: number
-	timestamp: Date
-	data: TData
-}

packages/aris-core/index.ts

@@ -1,5 +0,0 @@
-export type { Context, Location } from "./context"
-export type { FeedItem } from "./feed"
-export type { DataSource } from "./data-source"
-export type { ReconcilerConfig, ReconcileResult, SourceError } from "./reconciler"
-export { Reconciler } from "./reconciler"

packages/aris-core/package.json

@@ -2,8 +2,8 @@
 	"name": "@aris/core",
 	"version": "0.0.0",
 	"type": "module",
-	"main": "index.ts",
+	"main": "src/index.ts",
-	"types": "index.ts",
+	"types": "src/index.ts",
 	"scripts": {
 		"test": "bun test ."
 	}

packages/aris-core/reconciler.test.ts

@@ -1,240 +0,0 @@
-import { describe, expect, test } from "bun:test"
-
-import type { Context } from "./context"
-import type { DataSource } from "./data-source"
-import type { FeedItem } from "./feed"
-
-import { Reconciler } from "./reconciler"
-
-type WeatherData = { temp: number }
-type WeatherItem = FeedItem<"weather", WeatherData>
-
-type CalendarData = { title: string }
-type CalendarItem = FeedItem<"calendar", CalendarData>
-
-const createMockContext = (): Context => ({
-	time: new Date("2026-01-15T12:00:00Z"),
-})
-
-const createWeatherSource = (items: WeatherItem[], delay = 0): DataSource<WeatherItem> => ({
-	type: "weather",
-	async query() {
-		if (delay > 0) {
-			await new Promise((resolve) => setTimeout(resolve, delay))
-		}
-		return items
-	},
-})
-
-const createCalendarSource = (items: CalendarItem[]): DataSource<CalendarItem> => ({
-	type: "calendar",
-	async query() {
-		return items
-	},
-})
-
-const createFailingSource = (type: string, error: Error): DataSource<FeedItem> => ({
-	type,
-	async query() {
-		throw error
-	},
-})
-
-describe("Reconciler", () => {
-	test("returns empty result when no sources registered", async () => {
-		const reconciler = new Reconciler()
-		const result = await reconciler.reconcile(createMockContext())
-
-		expect(result.items).toEqual([])
-		expect(result.errors).toEqual([])
-	})
-
-	test("collects items from single source", async () => {
-		const items: WeatherItem[] = [
-			{
-				id: "weather-1",
-				type: "weather",
-				priority: 0.5,
-				timestamp: new Date(),
-				data: { temp: 20 },
-			},
-		]
-
-		const reconciler = new Reconciler().register(createWeatherSource(items))
-		const result = await reconciler.reconcile(createMockContext())
-
-		expect(result.items).toEqual(items)
-		expect(result.errors).toEqual([])
-	})
-
-	test("collects items from multiple sources", async () => {
-		const weatherItems: WeatherItem[] = [
-			{
-				id: "weather-1",
-				type: "weather",
-				priority: 0.5,
-				timestamp: new Date(),
-				data: { temp: 20 },
-			},
-		]
-
-		const calendarItems: CalendarItem[] = [
-			{
-				id: "calendar-1",
-				type: "calendar",
-				priority: 0.8,
-				timestamp: new Date(),
-				data: { title: "Meeting" },
-			},
-		]
-
-		const reconciler = new Reconciler()
-			.register(createWeatherSource(weatherItems))
-			.register(createCalendarSource(calendarItems))
-
-		const result = await reconciler.reconcile(createMockContext())
-
-		expect(result.items).toHaveLength(2)
-		expect(result.errors).toEqual([])
-	})
-
-	test("sorts items by priority descending", async () => {
-		const weatherItems: WeatherItem[] = [
-			{
-				id: "weather-1",
-				type: "weather",
-				priority: 0.2,
-				timestamp: new Date(),
-				data: { temp: 20 },
-			},
-		]
-
-		const calendarItems: CalendarItem[] = [
-			{
-				id: "calendar-1",
-				type: "calendar",
-				priority: 0.9,
-				timestamp: new Date(),
-				data: { title: "Meeting" },
-			},
-		]
-
-		const reconciler = new Reconciler()
-			.register(createWeatherSource(weatherItems))
-			.register(createCalendarSource(calendarItems))
-
-		const result = await reconciler.reconcile(createMockContext())
-
-		expect(result.items[0]?.id).toBe("calendar-1")
-		expect(result.items[1]?.id).toBe("weather-1")
-	})
-
-	test("captures errors from failing sources", async () => {
-		const error = new Error("Source failed")
-
-		const reconciler = new Reconciler().register(createFailingSource("failing", error))
-
-		const result = await reconciler.reconcile(createMockContext())
-
-		expect(result.items).toEqual([])
-		expect(result.errors).toHaveLength(1)
-		expect(result.errors[0]?.sourceType).toBe("failing")
-		expect(result.errors[0]?.error.message).toBe("Source failed")
-	})
-
-	test("returns partial results when some sources fail", async () => {
-		const items: WeatherItem[] = [
-			{
-				id: "weather-1",
-				type: "weather",
-				priority: 0.5,
-				timestamp: new Date(),
-				data: { temp: 20 },
-			},
-		]
-
-		const reconciler = new Reconciler()
-			.register(createWeatherSource(items))
-			.register(createFailingSource("failing", new Error("Failed")))
-
-		const result = await reconciler.reconcile(createMockContext())
-
-		expect(result.items).toHaveLength(1)
-		expect(result.errors).toHaveLength(1)
-	})
-
-	test("times out slow sources", async () => {
-		const items: WeatherItem[] = [
-			{
-				id: "weather-1",
-				type: "weather",
-				priority: 0.5,
-				timestamp: new Date(),
-				data: { temp: 20 },
-			},
-		]
-
-		const reconciler = new Reconciler({ timeout: 50 }).register(createWeatherSource(items, 100))
-
-		const result = await reconciler.reconcile(createMockContext())
-
-		expect(result.items).toEqual([])
-		expect(result.errors).toHaveLength(1)
-		expect(result.errors[0]?.sourceType).toBe("weather")
-		expect(result.errors[0]?.error.message).toContain("timed out")
-	})
-
-	test("unregister removes source", async () => {
-		const items: WeatherItem[] = [
-			{
-				id: "weather-1",
-				type: "weather",
-				priority: 0.5,
-				timestamp: new Date(),
-				data: { temp: 20 },
-			},
-		]
-
-		const reconciler = new Reconciler().register(createWeatherSource(items)).unregister("weather")
-
-		const result = await reconciler.reconcile(createMockContext())
-		expect(result.items).toEqual([])
-	})
-
-	test("infers discriminated union type from chained registers", async () => {
-		const weatherItems: WeatherItem[] = [
-			{
-				id: "weather-1",
-				type: "weather",
-				priority: 0.5,
-				timestamp: new Date(),
-				data: { temp: 20 },
-			},
-		]
-
-		const calendarItems: CalendarItem[] = [
-			{
-				id: "calendar-1",
-				type: "calendar",
-				priority: 0.8,
-				timestamp: new Date(),
-				data: { title: "Meeting" },
-			},
-		]
-
-		const reconciler = new Reconciler()
-			.register(createWeatherSource(weatherItems))
-			.register(createCalendarSource(calendarItems))
-
-		const { items } = await reconciler.reconcile(createMockContext())
-
-		// Type narrowing should work
-		for (const item of items) {
-			if (item.type === "weather") {
-				expect(typeof item.data.temp).toBe("number")
-			} else if (item.type === "calendar") {
-				expect(typeof item.data.title).toBe("string")
-			}
-		}
-	})
-})

packages/aris-core/src/context-bridge.ts

@@ -0,0 +1,102 @@
+import type { Context } from "./context"
+import type { ContextProvider } from "./context-provider"
+
+interface ContextUpdatable {
+	pushContextUpdate(update: Partial<Context>): void
+}
+
+export interface ProviderError {
+	key: string
+	error: Error
+}
+
+export interface RefreshResult {
+	errors: ProviderError[]
+}
+
+/**
+ * Bridges context providers to a feed controller.
+ *
+ * Subscribes to provider updates and forwards them to the controller.
+ * Supports manual refresh to gather current values from all providers.
+ *
+ * @example
+ * ```ts
+ * const controller = new FeedController()
+ *   .addDataSource(new WeatherDataSource())
+ *   .addDataSource(new TflDataSource())
+ *
+ * const bridge = new ContextBridge(controller)
+ *   .addProvider(new LocationProvider())
+ *   .addProvider(new MusicProvider())
+ *
+ * // Manual refresh gathers from all providers
+ * await bridge.refresh()
+ *
+ * // Cleanup
+ * bridge.stop()
+ * controller.stop()
+ * ```
+ */
+export class ContextBridge {
+	private controller: ContextUpdatable
+	private providers = new Map<string, ContextProvider>()
+	private cleanups: Array<() => void> = []
+
+	constructor(controller: ContextUpdatable) {
+		this.controller = controller
+	}
+
+	/**
+	 * Registers a context provider. Immediately subscribes to updates.
+	 */
+	addProvider<T>(provider: ContextProvider<T>): this {
+		this.providers.set(provider.key, provider as ContextProvider)
+
+		const cleanup = provider.onUpdate((value) => {
+			this.controller.pushContextUpdate({ [provider.key]: value })
+		})
+		this.cleanups.push(cleanup)
+
+		return this
+	}
+
+	/**
+	 * Gathers current values from all providers and pushes to controller.
+	 * Use for manual refresh when user pulls to refresh.
+	 * Returns errors from providers that failed to fetch.
+	 */
+	async refresh(): Promise<RefreshResult> {
+		const updates: Partial<Context> = {}
+		const errors: ProviderError[] = []
+
+		const entries = Array.from(this.providers.entries())
+		const results = await Promise.allSettled(
+			entries.map(([_, provider]) => provider.fetchCurrentValue()),
+		)
+
+		entries.forEach(([key], i) => {
+			const result = results[i]
+			if (result?.status === "fulfilled") {
+				updates[key] = result.value
+			} else if (result?.status === "rejected") {
+				errors.push({
+					key,
+					error: result.reason instanceof Error ? result.reason : new Error(String(result.reason)),
+				})
+			}
+		})
+
+		this.controller.pushContextUpdate(updates)
+
+		return { errors }
+	}
+
+	/**
+	 * Unsubscribes from all providers.
+	 */
+	stop(): void {
+		this.cleanups.forEach((cleanup) => cleanup())
+		this.cleanups = []
+	}
+}

packages/aris-core/src/context-provider.ts

@@ -0,0 +1,35 @@
+/**
+ * Provides context values reactively and on-demand.
+ *
+ * Implementations push updates when values change (reactive) and
+ * return current values when requested (for manual refresh).
+ *
+ * @example
+ * ```ts
+ * class LocationProvider implements ContextProvider<Location> {
+ *   readonly key = LocationKey
+ *
+ *   onUpdate(callback: (value: Location) => void): () => void {
+ *     const watchId = navigator.geolocation.watchPosition(pos => {
+ *       callback({ lat: pos.coords.latitude, lng: pos.coords.longitude, accuracy: pos.coords.accuracy })
+ *     })
+ *     return () => navigator.geolocation.clearWatch(watchId)
+ *   }
+ *
+ *   async fetchCurrentValue(): Promise<Location> {
+ *     const pos = await getCurrentPosition()
+ *     return { lat: pos.coords.latitude, lng: pos.coords.longitude, accuracy: pos.coords.accuracy }
+ *   }
+ * }
+ * ```
+ */
+export interface ContextProvider<T = unknown> {
+	/** The context key this provider populates */
+	readonly key: string
+
+	/** Subscribe to value changes. Returns cleanup function. */
+	onUpdate(callback: (value: T) => void): () => void
+
+	/** Fetch current value on-demand (used for manual refresh). */
+	fetchCurrentValue(): Promise<T>
+}

packages/aris-core/src/context.ts

@@ -0,0 +1,46 @@
+/**
+ * Branded type for type-safe context keys.
+ *
+ * Each package defines its own keys with associated value types:
+ * ```ts
+ * const LocationKey: ContextKey<Location> = contextKey("location")
+ * ```
+ */
+export type ContextKey<T> = string & { __contextValue?: T }
+
+/**
+ * Creates a typed context key.
+ *
+ * @example
+ * ```ts
+ * interface Location { lat: number; lng: number; accuracy: number }
+ * const LocationKey: ContextKey<Location> = contextKey("location")
+ * ```
+ */
+export function contextKey<T>(key: string): ContextKey<T> {
+	return key as ContextKey<T>
+}
+
+/**
+ * Type-safe accessor for context values.
+ *
+ * @example
+ * ```ts
+ * const location = contextValue(context, LocationKey)
+ * if (location) {
+ *   console.log(location.lat, location.lng)
+ * }
+ * ```
+ */
+export function contextValue<T>(context: Context, key: ContextKey<T>): T | undefined {
+	return context[key] as T | undefined
+}
+
+/**
+ * Arbitrary key-value bag representing the current state.
+ * Always includes `time`. Other keys are added by context providers.
+ */
+export interface Context {
+	time: Date
+	[key: string]: unknown
+}

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

@@ -0,0 +1,35 @@
+import type { Context } from "./context"
+import type { FeedItem } from "./feed"
+
+/**
+ * Produces feed items from an external source.
+ *
+ * @example
+ * ```ts
+ * type WeatherItem = FeedItem<"weather", { temp: number }>
+ *
+ * class WeatherDataSource implements DataSource<WeatherItem> {
+ *   readonly type = "weather"
+ *
+ *   async query(context: Context): Promise<WeatherItem[]> {
+ *     const location = contextValue(context, LocationKey)
+ *     if (!location) return []
+ *     const data = await fetchWeather(location)
+ *     return [{
+ *       id: `weather-${Date.now()}`,
+ *       type: this.type,
+ *       priority: 0.5,
+ *       timestamp: context.time,
+ *       data: { temp: data.temperature },
+ *     }]
+ *   }
+ * }
+ * ```
+ */
+export interface DataSource<TItem extends FeedItem = FeedItem, TConfig = unknown> {
+	/** Unique identifier for this source type */
+	readonly type: TItem["type"]
+
+	/** Queries the source and returns feed items */
+	query(context: Context, config: TConfig): Promise<TItem[]>
+}

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

@@ -0,0 +1,161 @@
+import type { Context } from "./context"
+import type { DataSource } from "./data-source"
+import type { FeedItem } from "./feed"
+import type { ReconcileResult } from "./reconciler"
+
+import { Reconciler } from "./reconciler"
+
+export interface FeedControllerConfig {
+	/** Timeout for each data source query in milliseconds */
+	timeout?: number
+	/** Debounce window for batching context updates (default: 100ms) */
+	debounceMs?: number
+	/** Initial context state */
+	initialContext?: Context
+}
+
+export type FeedSubscriber<TItems extends FeedItem> = (result: ReconcileResult<TItems>) => void
+
+interface RegisteredSource {
+	source: DataSource<FeedItem, unknown>
+	config: unknown
+}
+
+const DEFAULT_DEBOUNCE_MS = 100
+
+/**
+ * Orchestrates feed reconciliation in response to context updates.
+ *
+ * Holds context state, debounces updates, queries data sources, and
+ * notifies subscribers. Each user should have their own instance.
+ *
+ * @example
+ * ```ts
+ * const controller = new FeedController({ debounceMs: 100 })
+ *   .addDataSource(new WeatherDataSource())
+ *   .addDataSource(new TflDataSource())
+ *
+ * controller.subscribe((result) => {
+ *   console.log(result.items)
+ * })
+ *
+ * // Context update triggers debounced reconcile
+ * controller.pushContextUpdate({ [LocationKey]: location })
+ *
+ * // Direct reconcile (no debounce)
+ * const result = await controller.reconcile()
+ *
+ * // Cleanup
+ * controller.stop()
+ * ```
+ */
+export class FeedController<TItems extends FeedItem = never> {
+	private sources = new Map<string, RegisteredSource>()
+	private subscribers = new Set<FeedSubscriber<TItems>>()
+	private context: Context
+	private debounceMs: number
+	private timeout: number | undefined
+	private pendingTimeout: ReturnType<typeof setTimeout> | null = null
+	private stopped = false
+
+	constructor(config?: FeedControllerConfig) {
+		this.context = config?.initialContext ?? { time: new Date() }
+		this.debounceMs = config?.debounceMs ?? DEFAULT_DEBOUNCE_MS
+		this.timeout = config?.timeout
+	}
+
+	/** Registers a data source. */
+	addDataSource<TItem extends FeedItem, TConfig>(
+		source: DataSource<TItem, TConfig>,
+		config?: TConfig,
+	): FeedController<TItems | TItem> {
+		this.sources.set(source.type, {
+			source: source as DataSource<FeedItem, unknown>,
+			config,
+		})
+		return this as FeedController<TItems | TItem>
+	}
+
+	/** Removes a data source by type. */
+	removeDataSource<T extends TItems["type"]>(
+		sourceType: T,
+	): FeedController<Exclude<TItems, { type: T }>> {
+		this.sources.delete(sourceType)
+		return this as unknown as FeedController<Exclude<TItems, { type: T }>>
+	}
+
+	/** Stops the controller and cancels pending reconciles. */
+	stop(): void {
+		this.stopped = true
+
+		if (this.pendingTimeout) {
+			clearTimeout(this.pendingTimeout)
+			this.pendingTimeout = null
+		}
+	}
+
+	/** Merges update into context and schedules a debounced reconcile. */
+	pushContextUpdate(update: Partial<Context>): void {
+		this.context = { ...this.context, ...update, time: new Date() }
+		this.scheduleReconcile()
+	}
+
+	/** Subscribes to feed updates. Returns unsubscribe function. */
+	subscribe(callback: FeedSubscriber<TItems>): () => void {
+		this.subscribers.add(callback)
+
+		return () => {
+			this.subscribers.delete(callback)
+		}
+	}
+
+	/** Immediately reconciles with current or provided context. */
+	async reconcile(context?: Context): Promise<ReconcileResult<TItems>> {
+		const ctx = context ?? this.context
+		const reconciler = this.createReconciler()
+		return reconciler.reconcile(ctx)
+	}
+
+	/** Returns current context. */
+	getContext(): Context {
+		return this.context
+	}
+
+	private scheduleReconcile(): void {
+		if (this.pendingTimeout) return
+
+		this.pendingTimeout = setTimeout(() => {
+			this.flushPending()
+		}, this.debounceMs)
+	}
+
+	private async flushPending(): Promise<void> {
+		this.pendingTimeout = null
+
+		if (this.stopped) return
+		if (this.sources.size === 0) return
+
+		const reconciler = this.createReconciler()
+		const result = await reconciler.reconcile(this.context)
+
+		this.notifySubscribers(result)
+	}
+
+	private createReconciler(): Reconciler<TItems> {
+		const reconciler = new Reconciler<TItems>({ timeout: this.timeout })
+		Array.from(this.sources.values()).forEach(({ source, config }) => {
+			reconciler.register(source, config)
+		})
+		return reconciler as Reconciler<TItems>
+	}
+
+	private notifySubscribers(result: ReconcileResult<TItems>): void {
+		this.subscribers.forEach((callback) => {
+			try {
+				callback(result)
+			} catch {
+				// Subscriber errors shouldn't break other subscribers
+			}
+		})
+	}
+}

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

@@ -0,0 +1,422 @@
+import { describe, expect, test } from "bun:test"
+
+import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
+
+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 []
+		},
+	}
+}
+
+// =============================================================================
+// GRAPH SIMULATION (until FeedController is updated)
+// =============================================================================
+
+interface SourceGraph {
+	sources: Map<string, FeedSource>
+	sorted: FeedSource[]
+	dependents: Map<string, string[]>
+}
+
+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 }
+}
+
+async function refreshGraph(graph: SourceGraph): Promise<{ context: Context; items: FeedItem[] }> {
+	let context: Context = { time: new Date() }
+
+	// Run fetchContext in topological order
+	for (const source of graph.sorted) {
+		if (source.fetchContext) {
+			const update = await source.fetchContext(context)
+			context = { ...context, ...update }
+		}
+	}
+
+	// Run fetchItems on all sources
+	const items: FeedItem[] = []
+	for (const source of graph.sorted) {
+		if (source.fetchItems) {
+			const sourceItems = await source.fetchItems(context)
+			items.push(...sourceItems)
+		}
+	}
+
+	// Sort by priority descending
+	items.sort((a, b) => b.priority - a.priority)
+
+	return { context, items }
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe("FeedSource", () => {
+	describe("interface", () => {
+		test("source with only context production", () => {
+			const source = createLocationSource()
+
+			expect(source.id).toBe("location")
+			expect(source.dependencies).toBeUndefined()
+			expect(source.fetchContext).toBeDefined()
+			expect(source.onContextUpdate).toBeDefined()
+			expect(source.fetchItems).toBeUndefined()
+		})
+
+		test("source with dependencies and both context and items", () => {
+			const source = createWeatherSource()
+
+			expect(source.id).toBe("weather")
+			expect(source.dependencies).toEqual(["location"])
+			expect(source.fetchContext).toBeDefined()
+			expect(source.fetchItems).toBeDefined()
+		})
+
+		test("source with only item production", () => {
+			const source = createAlertSource()
+
+			expect(source.id).toBe("alert")
+			expect(source.dependencies).toEqual(["weather"])
+			expect(source.fetchContext).toBeUndefined()
+			expect(source.fetchItems).toBeDefined()
+		})
+	})
+
+	describe("graph validation", () => {
+		test("validates all dependencies exist", () => {
+			const orphan: FeedSource = {
+				id: "orphan",
+				dependencies: ["nonexistent"],
+			}
+
+			expect(() => buildGraph([orphan])).toThrow(
+				'Source "orphan" depends on "nonexistent" which is not registered',
+			)
+		})
+
+		test("detects circular dependencies", () => {
+			const a: FeedSource = { id: "a", dependencies: ["b"] }
+			const b: FeedSource = { id: "b", dependencies: ["a"] }
+
+			expect(() => buildGraph([a, b])).toThrow("Circular dependency detected: a → b → a")
+		})
+
+		test("detects longer cycles", () => {
+			const a: FeedSource = { id: "a", dependencies: ["c"] }
+			const b: FeedSource = { id: "b", dependencies: ["a"] }
+			const c: FeedSource = { id: "c", dependencies: ["b"] }
+
+			expect(() => buildGraph([a, b, c])).toThrow("Circular dependency detected")
+		})
+
+		test("topologically sorts sources", () => {
+			const location = createLocationSource()
+			const weather = createWeatherSource()
+			const alert = createAlertSource()
+
+			// Register in wrong order
+			const graph = buildGraph([alert, weather, location])
+
+			expect(graph.sorted.map((s) => s.id)).toEqual(["location", "weather", "alert"])
+		})
+
+		test("builds reverse dependency map", () => {
+			const location = createLocationSource()
+			const weather = createWeatherSource()
+			const alert = createAlertSource()
+
+			const graph = buildGraph([location, weather, alert])
+
+			expect(graph.dependents.get("location")).toEqual(["weather"])
+			expect(graph.dependents.get("weather")).toEqual(["alert"])
+			expect(graph.dependents.get("alert")).toBeUndefined()
+		})
+	})
+
+	describe("graph 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 graph = buildGraph([weather, location])
+			await refreshGraph(graph)
+
+			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 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" })
+		})
+
+		test("collects items from all sources", async () => {
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			const weather = createWeatherSource()
+
+			const graph = buildGraph([location, weather])
+			const { items } = await refreshGraph(graph)
+
+			expect(items).toHaveLength(1)
+			expect(items[0]!.type).toBe("weather")
+		})
+
+		test("downstream source receives upstream context", async () => {
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			const weather = createWeatherSource(async () => ({
+				temperature: 15,
+				condition: "storm",
+			}))
+
+			const alert = createAlertSource()
+
+			const graph = buildGraph([location, weather, alert])
+			const { items } = await refreshGraph(graph)
+
+			expect(items).toHaveLength(2)
+			expect(items[0]!.type).toBe("alert") // priority 1.0
+			expect(items[1]!.type).toBe("weather") // priority 0.5
+		})
+
+		test("source without location context returns empty items", async () => {
+			// Location source exists but hasn't been updated (returns default 0,0)
+			const location: FeedSource = {
+				id: "location",
+				async fetchContext() {
+					// Simulate no location available
+					return {}
+				},
+			}
+
+			const weather = createWeatherSource()
+
+			const graph = buildGraph([location, weather])
+			const { context, items } = await refreshGraph(graph)
+
+			expect(contextValue(context, WeatherKey)).toBeUndefined()
+			expect(items).toHaveLength(0)
+		})
+	})
+
+	describe("reactive updates", () => {
+		test("onContextUpdate receives callback and returns cleanup", () => {
+			const location = createLocationSource()
+			let updateCount = 0
+
+			const cleanup = location.onContextUpdate!(
+				() => {
+					updateCount++
+				},
+				() => ({ time: new Date() }),
+			)
+
+			location.simulateUpdate({ lat: 1, lng: 1 })
+			expect(updateCount).toBe(1)
+
+			location.simulateUpdate({ lat: 2, lng: 2 })
+			expect(updateCount).toBe(2)
+
+			cleanup()
+
+			location.simulateUpdate({ lat: 3, lng: 3 })
+			expect(updateCount).toBe(2) // no more updates after cleanup
+		})
+	})
+})

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

@@ -0,0 +1,76 @@
+import type { Context } from "./context"
+import type { FeedItem } from "./feed"
+
+/**
+ * Unified interface for sources that provide context and/or feed items.
+ *
+ * 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
+ *
+ * @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)
+ *   },
+ * }
+ * ```
+ */
+export interface FeedSource<TItem extends FeedItem = FeedItem> {
+	/** Unique identifier for this source */
+	readonly id: string
+
+	/** IDs of sources this source depends on */
+	readonly dependencies?: readonly string[]
+
+	/**
+	 * Subscribe to reactive context updates.
+	 * Called when the source can push context changes proactively.
+	 * Returns cleanup function.
+	 */
+	onContextUpdate?(
+		callback: (update: Partial<Context>) => void,
+		getContext: () => Context,
+	): () => void
+
+	/**
+	 * Fetch context on-demand.
+	 * Called during manual refresh or initial load.
+	 */
+	fetchContext?(context: Context): Promise<Partial<Context>>
+
+	/**
+	 * Subscribe to reactive feed item updates.
+	 * Called when the source can push item changes proactively.
+	 * Returns cleanup function.
+	 */
+	onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void
+
+	/**
+	 * Fetch feed items on-demand.
+	 * Called during manual refresh or when dependencies update.
+	 */
+	fetchItems?(context: Context): Promise<TItem[]>
+}

packages/aris-core/src/feed.ts

@@ -0,0 +1,31 @@
+/**
+ * A single item in the feed.
+ *
+ * @example
+ * ```ts
+ * type WeatherItem = FeedItem<"weather", { temp: number; condition: string }>
+ *
+ * const item: WeatherItem = {
+ *   id: "weather-123",
+ *   type: "weather",
+ *   priority: 0.5,
+ *   timestamp: new Date(),
+ *   data: { temp: 18, condition: "cloudy" },
+ * }
+ * ```
+ */
+export interface FeedItem<
+	TType extends string = string,
+	TData extends Record<string, unknown> = Record<string, unknown>,
+> {
+	/** Unique identifier */
+	id: string
+	/** Item type, matches the data source type */
+	type: TType
+	/** Sort priority (higher = more important, shown first) */
+	priority: number
+	/** When this item was generated */
+	timestamp: Date
+	/** Type-specific payload */
+	data: TData
+}

packages/aris-core/src/index.ts

@@ -0,0 +1,27 @@
+// Context
+export type { Context, ContextKey } from "./context"
+export { contextKey, contextValue } from "./context"
+
+// Feed
+export type { FeedItem } from "./feed"
+
+// Feed Source
+export type { FeedSource } from "./feed-source"
+
+// Data Source (deprecated - use FeedSource)
+export type { DataSource } from "./data-source"
+
+// Context Provider
+export type { ContextProvider } from "./context-provider"
+
+// Context Bridge
+export type { ProviderError, RefreshResult } from "./context-bridge"
+export { ContextBridge } from "./context-bridge"
+
+// Reconciler
+export type { ReconcileResult, ReconcilerConfig, SourceError } from "./reconciler"
+export { Reconciler } from "./reconciler"
+
+// Feed Controller
+export type { FeedControllerConfig, FeedSubscriber } from "./feed-controller"
+export { FeedController } from "./feed-controller"

packages/aris-data-source-tfl/src/data-source.ts

@@ -1,5 +1,5 @@
 import type { Context, DataSource } from "@aris/core"
-import { TflApi, type ITflApi } from "./tfl-api.ts"
+
 import type {
 	StationLocation,
 	TflAlertData,
@@ -10,6 +10,8 @@ import type {
 	TflLineId,
 } from "./types.ts"
 
+import { TflApi, type ITflApi } from "./tfl-api.ts"
+
 const SEVERITY_PRIORITY: Record<TflAlertSeverity, number> = {
 	closure: 100,
 	"major-delays": 80,
@@ -22,7 +24,10 @@ function haversineDistance(lat1: number, lng1: number, lat2: number, lng2: numbe
 	const dLng = ((lng2 - lng1) * Math.PI) / 180
 	const a =
 		Math.sin(dLat / 2) * Math.sin(dLat / 2) +
-		Math.cos((lat1 * Math.PI) / 180) * Math.cos((lat2 * Math.PI) / 180) * Math.sin(dLng / 2) * Math.sin(dLng / 2)
+		Math.cos((lat1 * Math.PI) / 180) *
+			Math.cos((lat2 * Math.PI) / 180) *
+			Math.sin(dLng / 2) *
+			Math.sin(dLng / 2)
 	const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
 	return R * c
 }
@@ -62,13 +67,20 @@ export class TflDataSource implements DataSource<TflAlertFeedItem, TflDataSource
 	}
 
 	async query(context: Context, config: TflDataSourceConfig): Promise<TflAlertFeedItem[]> {
-		const [statuses, stations] = await Promise.all([this.api.fetchLineStatuses(config.lines), this.api.fetchStations()])
+		const [statuses, stations] = await Promise.all([
+			this.api.fetchLineStatuses(config.lines),
+			this.api.fetchStations(),
+		])
 
 		const items: TflAlertFeedItem[] = statuses.map((status) => {
-			const closestStationDistance =
+			const closestStationDistance = context.location
-				context.location ?
+				? findClosestStationDistance(
-					findClosestStationDistance(status.lineId, stations, context.location.lat, context.location.lng)
+						status.lineId,
-				:	null
+						stations,
+						context.location.lat,
+						context.location.lng,
+					)
+				: null
 
 			const data: TflAlertData = {
 				line: status.lineId,

packages/aris-data-source-tfl/src/integration.test.ts

@@ -1,11 +1,12 @@
+import type { Context } from "@aris/core"
+
 import { describe, expect, test } from "bun:test"
 
-import type { Context } from "@aris/core"
-import { TflDataSource } from "./data-source.ts"
 import type { ITflApi, TflLineStatus } from "./tfl-api.ts"
 import type { StationLocation, TflLineId } from "./types.ts"
 
 import fixtures from "../fixtures/tfl-responses.json"
+import { TflDataSource } from "./data-source.ts"
 
 // Mock API that returns fixture data
 class FixtureTflApi implements ITflApi {
@@ -109,9 +110,10 @@ describe("TfL Feed Items (using fixture data)", () => {
 			expect(typeof item.data.lineName).toBe("string")
 			expect(["minor-delays", "major-delays", "closure"]).toContain(item.data.severity)
 			expect(typeof item.data.description).toBe("string")
-			expect(item.data.closestStationDistance === null || typeof item.data.closestStationDistance === "number").toBe(
+			expect(
-				true,
+				item.data.closestStationDistance === null ||
-			)
+					typeof item.data.closestStationDistance === "number",
+			).toBe(true)
 		}
 	})
 

packages/aris-data-source-tfl/src/tfl-api.ts

@@ -1,4 +1,5 @@
 import { type } from "arktype"
+
 import type { StationLocation, TflAlertSeverity } from "./types.ts"
 
 const TFL_API_BASE = "https://api.tfl.gov.uk"

packages/aris-data-source-tfl/src/types.ts

@@ -1,4 +1,5 @@
 import type { FeedItem } from "@aris/core"
+
 import type { TflLineId } from "./tfl-api.ts"
 
 export type { TflLineId } from "./tfl-api.ts"