feat(backend): add LLM-powered feed enhancement (#58)

* feat(backend): add LLM-powered feed enhancement

Add enhancement harness that fills feed item slots and
generates synthetic items via OpenRouter.

- LLM client with 30s timeout, reusable SDK instance
- Prompt builder with mini calendar and week overview
- arktype schema validation + JSON Schema for structured output
- Pure merge function with clock injection
- Defensive fallback in feed endpoint on enhancement failure
- Skips LLM call when no unfilled slots or no API key

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

* refactor: move feed enhancement into UserSession

Move enhancement logic from HTTP handler into UserSession so the
transport layer has no knowledge of enhancement. UserSession.feed()
handles refresh, enhancement, and caching in one place.

- UserSession subscribes to engine updates and re-enhances eagerly
- Enhancement cache tracks source identity to prevent stale results
- UserSessionManager accepts config object with optional enhancer
- HTTP handler simplified to just call session.feed()

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

* test: add schema sync tests for arktype/JSON Schema drift

Validates reference payloads against both the arktype schema
(parseEnhancementResult) and the OpenRouter JSON Schema structure.
Catches field additions/removals or type changes in either schema.

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

* refactor: rename arktype schemas to match types

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

---------

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

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

@@ -1,11 +1,11 @@
-import type { ActionDefinition, ContextEntry, FeedSource } from "@aris/core"
+import type { ActionDefinition, ContextEntry, FeedItem, FeedSource } from "@aris/core"
 
 import { LocationSource } from "@aris/source-location"
 import { describe, expect, test } from "bun:test"
 
 import { UserSession } from "./user-session.ts"
 
-function createStubSource(id: string): FeedSource {
+function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
 	return {
 		id,
 		async listActions(): Promise<Record<string, ActionDefinition>> {
@@ -18,7 +18,7 @@ function createStubSource(id: string): FeedSource {
 			return null
 		},
 		async fetchItems() {
-			return []
+			return items
 		},
 	}
 }
@@ -70,3 +70,141 @@ describe("UserSession", () => {
 		expect(location.lastLocation!.lat).toBe(51.5)
 	})
 })
+
+describe("UserSession.feed", () => {
+	test("returns feed items without enhancer", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const session = new UserSession([createStubSource("test", items)])
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+	})
+
+	test("returns enhanced items when enhancer is provided", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async (feedItems: FeedItem[]) =>
+			feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.data.enhanced).toBe(true)
+	})
+
+	test("caches enhanced items on subsequent calls", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		let enhancerCallCount = 0
+		const enhancer = async (feedItems: FeedItem[]) => {
+			enhancerCallCount++
+			return feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+		}
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancerCallCount).toBe(1)
+	})
+
+	test("re-enhances after engine refresh with new data", async () => {
+		let currentItems: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { version: 1 },
+			},
+		]
+		const source = createStubSource("test", currentItems)
+		// Make fetchItems dynamic so refresh returns new data
+		source.fetchItems = async () => currentItems
+
+		const enhancedVersions: number[] = []
+		const enhancer = async (feedItems: FeedItem[]) => {
+			const version = feedItems[0]!.data.version as number
+			enhancedVersions.push(version)
+			return feedItems.map((item) => ({
+				...item,
+				data: { ...item.data, enhanced: true },
+			}))
+		}
+
+		const session = new UserSession([source], enhancer)
+
+		// First feed triggers refresh + enhancement
+		const result1 = await session.feed()
+		expect(result1.items[0]!.data.version).toBe(1)
+		expect(result1.items[0]!.data.enhanced).toBe(true)
+
+		// Update source data and trigger engine refresh
+		currentItems = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-02T00:00:00.000Z"),
+				data: { version: 2 },
+			},
+		]
+		await session.engine.refresh()
+
+		// Wait for subscriber-triggered background enhancement
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		// feed() should now serve re-enhanced items with version 2
+		const result2 = await session.feed()
+		expect(result2.items[0]!.data.version).toBe(2)
+		expect(result2.items[0]!.data.enhanced).toBe(true)
+		expect(enhancedVersions).toEqual([1, 2])
+	})
+
+	test("falls back to unenhanced items when enhancer throws", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const enhancer = async () => {
+			throw new Error("enhancement exploded")
+		}
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		const result = await session.feed()
+
+		expect(result.items).toHaveLength(1)
+		expect(result.items[0]!.id).toBe("item-1")
+		expect(result.items[0]!.data.value).toBe(42)
+	})
+})