feat(core): add FeedSource interface

Unifies DataSource and ContextProvider into a single interface that
forms a dependency graph. Sources declare dependencies on other sources
and can provide context, feed items, or both.

Deprecates DataSource, ContextProvider, and ContextBridge.

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

packages/aris-core/src/feed-source.example.txt

@@ -0,0 +1,134 @@
+/**
+ * Example wiring of FeedSource graph.
+ * NOT for documentation - just to visualize the interface.
+ */
+
+import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
+import { contextKey, contextValue } from "./index"
+
+// ============================================================================
+// Context Keys - exported by each package
+// ============================================================================
+
+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
+// ============================================================================
+
+interface WeatherFeedItem extends FeedItem<"weather", { temperature: number; condition: string }> {}
+
+// ============================================================================
+// Sources
+// ============================================================================
+
+// Location source - context only, no feed items
+const locationSource: FeedSource = {
+	id: "location",
+
+	onContextUpdate(callback, _getContext) {
+		// Reactive: browser pushes location changes
+		const watchId = navigator.geolocation.watchPosition((pos) => {
+			callback({
+				[LocationKey]: {
+					lat: pos.coords.latitude,
+					lng: pos.coords.longitude,
+				},
+			})
+		})
+		return () => navigator.geolocation.clearWatch(watchId)
+	},
+
+	async fetchContext(_context) {
+		// On-demand: manual refresh
+		const pos = await new Promise<GeolocationPosition>((resolve, reject) => {
+			navigator.geolocation.getCurrentPosition(resolve, reject)
+		})
+		return {
+			[LocationKey]: {
+				lat: pos.coords.latitude,
+				lng: pos.coords.longitude,
+			},
+		}
+	},
+}
+
+// Weather source - depends on location, provides context + feed items
+const weatherSource: FeedSource<WeatherFeedItem> = {
+	id: "weather",
+	dependencies: ["location"],
+
+	async fetchContext(context) {
+		const location = contextValue(context, LocationKey)
+		if (!location) return {}
+
+		// Fetch weather from API
+		const weather = await fetchWeatherFromApi(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,
+				},
+			},
+		]
+	},
+}
+
+// ============================================================================
+// Graph wiring (conceptual - FeedSourceGraph not yet implemented)
+// ============================================================================
+
+// const graph = new FeedSourceGraph([
+//   locationSource,
+//   weatherSource,
+// ])
+//
+// // Graph validates:
+// // - All dependencies exist
+// // - No circular dependencies
+// // - Topologically sorts sources
+//
+// // On refresh:
+// // 1. fetchContext on location (no deps)
+// // 2. fetchContext on weather (has location in context now)
+// // 3. fetchItems on all sources
+// // 4. Return combined feed items
+//
+// // On reactive update from location:
+// // 1. Update context with new location
+// // 2. Trigger weather.fetchContext (it depends on location)
+// // 3. Trigger weather.fetchItems
+// // 4. Notify subscribers
+
+// ============================================================================
+// Helpers (mock)
+// ============================================================================
+
+async function fetchWeatherFromApi(_location: Location): Promise<Weather> {
+	return { temperature: 20, condition: "sunny" }
+}
+
+export { locationSource, weatherSource }

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/index.ts

@@ -5,7 +5,10 @@ export { contextKey, contextValue } from "./context"
 // Feed
 export type { FeedItem } from "./feed"
 
-// Data Source
+// Feed Source
+export type { FeedSource } from "./feed-source"
+
+// Data Source (deprecated - use FeedSource)
 export type { DataSource } from "./data-source"
 
 // Context Provider