@sriinnu/harmon-core 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @sriinnu/harmon-core
+
+![logo](./logo.svg)
+
+> Mood-aware session engine with track ranking, energy arc modulation, and adaptive playback.
+
+## Install
+
+```bash
+pnpm add @sriinnu/harmon-core
+```
+
+## Quick Start
+
+```typescript
+import { createEngine } from '@sriinnu/harmon-core';
+
+const engine = createEngine({ provider, playback, store });
+await engine.start({ version: 1, mode: 'focus' });
+engine.on('track.started', (track) => console.log(track.name));
+await engine.stop();
+```
+
+## API
+
+| Export | Description |
+|---|---|
+| `createEngine(config)` | Create a session engine instance |
+| `rankTracks(tracks, policy)` | Score and sort tracks against a session policy |
+| `fetchCandidates(sources)` | Gather candidate tracks from configured providers |
+| `calculateArcModulation(elapsed, arc)` | Compute energy multiplier for current position in arc |
+| `checkRecencyPenalty(track, history)` | Penalize recently played tracks/artists |
+| `SessionEngine` | Engine instance type |
+| `EngineConfig` | Configuration type |
+| `AudioFeatures` | Spotify-style audio feature vector |
+| `SessionState` | Current engine state |
+| `RankedTrack` | Track with computed score |
+
+## Architecture
+
+harmon-core is the central orchestrator. It consumes a `SessionPolicy` from harmon-protocol, pulls candidates from provider packages (harmon-spotify, harmon-apple, harmon-youtube), ranks them against soft/hard constraints, and drives playback through the active provider's controller.
+
+## License
+
+GNU Affero General Public License v3.0 only. See [LICENSE](../../LICENSE).

package/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: harmon-core
+description: Session engine with track ranking, candidate sourcing, and energy arc modulation
+capabilities:
+  - Create and manage music listening sessions with policy-driven behavior
+  - Rank candidate tracks using soft weights, hard constraints, and recency penalties
+  - Fetch candidates from multiple music providers and blend discovery ratios
+tags:
+  - engine
+  - ranking
+  - session
+  - music
+provider: harmon
+version: 0.1.0
+---
+
+# Harmon Core
+
+## What this does
+harmon-core is the decision-making engine at the heart of harmon. It accepts a SessionPolicy, sources candidate tracks from one or more MusicProvider adapters, ranks them according to soft weights, energy arcs, and hard constraints, and drives playback through a PlaybackController. It also tracks play history to apply recency penalties and prevent repetition.
+
+## When to use
+- Building a new session orchestrator or daemon that needs track selection logic
+- Integrating a new music provider that must participate in ranking and queue filling
+- Customizing how tracks are scored, filtered, or ordered during a session
+
+## Key exports
+- `createEngine` — factory that wires providers, store, and policy into a running SessionEngine
+- `MusicProvider` — interface for any streaming backend (Spotify, Apple, YouTube, etc.)
+- `PlaybackController` — interface for play/pause/skip/seek on a device
+- `AudioFeatures` — normalized audio feature vector (energy, tempo, valence, etc.)
+- `rankTracks` — pure function that scores and sorts a list of TrackWithFeatures
+- `fetchCandidates` — pulls tracks from configured sources and deduplicates them
+
+## Example
+```typescript
+import { createEngine } from '@sriinnu/harmon-core';
+
+const engine = createEngine({
+  providers: [spotifyProvider],
+  playback: spotifyPlayback,
+  store,
+  policy: { version: 1, mode: 'focus' },
+});
+engine.on('track.started', (e) => console.log(e));
+await engine.start();
+```

package/dist/arc.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Energy arc modulation for session progression
+ */
+import type { EnergyArc } from '@sriinnu/harmon-protocol';
+/**
+ * Calculate energy arc modulation based on session progress
+ *
+ * Returns: -0.5 to +0.5 modifier to apply to target energy
+ *
+ * @param elapsedMs Milliseconds elapsed since session start
+ * @param arc Energy arc configuration
+ * @param durationMs Total session duration (optional)
+ * @returns Energy modulation value
+ */
+export declare function calculateArcModulation(elapsedMs: number, arc?: EnergyArc, durationMs?: number): number;
+//# sourceMappingURL=arc.d.ts.map

package/dist/arc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arc.d.ts","sourceRoot":"","sources":["../src/arc.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,GAAG,CAAC,EAAE,SAAS,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAsER"}

package/dist/arc.js

@@ -0,0 +1,79 @@
+/**
+ * Energy arc modulation for session progression
+ */
+/**
+ * Calculate energy arc modulation based on session progress
+ *
+ * Returns: -0.5 to +0.5 modifier to apply to target energy
+ *
+ * @param elapsedMs Milliseconds elapsed since session start
+ * @param arc Energy arc configuration
+ * @param durationMs Total session duration (optional)
+ * @returns Energy modulation value
+ */
+export function calculateArcModulation(elapsedMs, arc, durationMs) {
+    if (!arc || !arc.shape || arc.shape === 'flat') {
+        return 0;
+    }
+    const totalDuration = durationMs || 3600000; // Default 1 hour
+    const progress = Math.min(elapsedMs / totalDuration, 1); // 0-1
+    const warmupMs = arc.warmupMs || 0;
+    const cooldownMs = arc.cooldownMs || 0;
+    const warmupProgress = warmupMs > 0 ? Math.min(elapsedMs / warmupMs, 1) : 1;
+    const cooldownProgress = cooldownMs > 0 && durationMs
+        ? Math.max(0, (elapsedMs - (durationMs - cooldownMs)) / cooldownMs)
+        : 0;
+    switch (arc.shape) {
+        case 'ramp-up': {
+            // Start low (-0.3), end high (+0.3)
+            if (warmupProgress < 1) {
+                return -0.3 * (1 - warmupProgress); // Warming up: -0.3 → 0
+            }
+            // Post-warmup: use adjusted progress for continuity
+            // At warmup end, this yields 0. At session end, yields +0.3.
+            const postWarmupProgress = warmupMs > 0
+                ? Math.min((elapsedMs - warmupMs) / Math.max(totalDuration - warmupMs, 1), 1)
+                : progress;
+            // Without warmup: -0.3 + 0.6*progress (full range -0.3 to +0.3)
+            // With warmup: 0 + 0.3*postProgress (0 to +0.3, continuous from warmup end)
+            if (warmupMs > 0) {
+                return 0.3 * postWarmupProgress;
+            }
+            return -0.3 + (0.6 * progress);
+        }
+        case 'ramp-down': {
+            // Start high (+0.3), end low (-0.3)
+            if (warmupProgress < 1) {
+                return 0.3 * warmupProgress; // Warming up: 0 → +0.3
+            }
+            if (cooldownProgress > 0) {
+                // During cooldown, ramp to negative
+                const preCooldownValue = warmupMs > 0
+                    ? (() => {
+                        const postProg = Math.min((durationMs - cooldownMs - warmupMs) / Math.max(totalDuration - warmupMs, 1), 1);
+                        return 0.3 - (0.6 * postProg);
+                    })()
+                    : 0.3 - (0.6 * ((durationMs - cooldownMs) / totalDuration));
+                return preCooldownValue + ((-0.3 - preCooldownValue) * cooldownProgress);
+            }
+            // Post-warmup: linear ramp from +0.3 to -0.3
+            if (warmupMs > 0) {
+                const postWarmupProgress = Math.min((elapsedMs - warmupMs) / Math.max(totalDuration - warmupMs, 1), 1);
+                return 0.3 - (0.6 * postWarmupProgress);
+            }
+            return 0.3 - (0.6 * progress);
+        }
+        case 'wave':
+            // Sine wave: low -> high -> low
+            if (warmupProgress < 1) {
+                return -0.3 * (1 - warmupProgress);
+            }
+            if (cooldownProgress > 0) {
+                return -0.3 * cooldownProgress;
+            }
+            return 0.3 * Math.sin(progress * Math.PI); // Peak at middle
+        default:
+            return 0;
+    }
+}
+//# sourceMappingURL=arc.js.map

package/dist/arc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arc.js","sourceRoot":"","sources":["../src/arc.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Session engine - Core orchestrator for session lifecycle and queue management
+ *
+ * Provider-agnostic: works with any MusicProvider + PlaybackController.
+ */
+import type { SessionPolicy, TrackInfo } from '@sriinnu/harmon-protocol';
+import type { MusicProvider, PlaybackController, SessionState, EventCallback, EngineLogger, SessionStore } from './types.js';
+export interface SessionEngine {
+    start(policy: SessionPolicy): Promise<void>;
+    stop(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    nudge(direction: 'calmer' | 'sharper', amount?: number): Promise<void>;
+    getQueue(): TrackInfo[];
+    getState(): SessionState | null;
+    refillQueue(): Promise<void>;
+    recordPlay(track: TrackInfo): Promise<void>;
+}
+export interface EngineConfig {
+    provider: MusicProvider;
+    playback: PlaybackController;
+    store: SessionStore;
+    onEvent?: EventCallback;
+    /** Optional logger for engine internals. Falls back to no-op if omitted. */
+    logger?: EngineLogger;
+}
+export declare function createEngine(config: EngineConfig): SessionEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,aAAa,EAEb,YAAY,EAEZ,YAAY,EACb,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,QAAQ,IAAI,SAAS,EAAE,CAAC;IACxB,QAAQ,IAAI,YAAY,GAAG,IAAI,CAAC;IAChC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AA+VD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,CAEhE"}

package/dist/engine.js

@@ -0,0 +1,285 @@
+/**
+ * Session engine - Core orchestrator for session lifecycle and queue management
+ *
+ * Provider-agnostic: works with any MusicProvider + PlaybackController.
+ */
+import { fetchCandidates } from './sources.js';
+import { rankTracks } from './ranking.js';
+class SessionEngineImpl {
+    provider;
+    playback;
+    store;
+    onEvent;
+    logger;
+    state = null;
+    refillInterval = null;
+    refilling = false;
+    // Constants
+    REFILL_CHECK_INTERVAL_MS = 10000; // Check every 10s
+    constructor(config) {
+        this.provider = config.provider;
+        this.playback = config.playback;
+        this.store = config.store;
+        this.onEvent = config.onEvent || (() => { });
+        this.logger = config.logger || { warn: () => { }, error: () => { } };
+    }
+    async start(policy) {
+        if (this.state !== null) {
+            throw new Error('Session already active. Stop current session first.');
+        }
+        // Create session in store
+        const sessionId = await this.store.createSession(JSON.stringify(policy));
+        // Initialize state
+        this.state = {
+            id: sessionId,
+            policy,
+            startedAt: Date.now(),
+            status: 'running',
+            history: [],
+            currentTrack: null,
+            queuedTracks: [],
+        };
+        // Initial queue fill
+        await this.refillQueue();
+        // Start auto-refill monitoring
+        this.startRefillMonitoring();
+        // Emit event
+        this.emit({
+            type: 'session.started',
+            payload: {
+                sessionId,
+                policy,
+                startedAt: this.state.startedAt,
+            },
+        });
+        await this.store.logEvent('session.started', { sessionId, policy }, sessionId);
+    }
+    async stop() {
+        if (!this.state) {
+            throw new Error('No active session');
+        }
+        const stoppedState = this.state;
+        const elapsedMs = Date.now() - stoppedState.startedAt;
+        // Stop monitoring
+        this.stopRefillMonitoring();
+        // Clear the live session before store finalization so a persistence error
+        // cannot strand a ghost in-memory session.
+        this.state = null;
+        // End session in store
+        await this.store.endSession(stoppedState.id);
+        await this.store.logEvent('session.stopped', { sessionId: stoppedState.id }, stoppedState.id);
+        // Emit event
+        this.emit({
+            type: 'session.stopped',
+            payload: {
+                sessionId: stoppedState.id,
+                elapsedMs,
+                duration: elapsedMs,
+                durationMs: elapsedMs,
+            },
+        });
+    }
+    async pause() {
+        if (!this.state) {
+            throw new Error('No active session');
+        }
+        this.state.status = 'paused';
+        this.stopRefillMonitoring();
+    }
+    async resume() {
+        if (!this.state) {
+            throw new Error('No active session');
+        }
+        this.state.status = 'running';
+        this.startRefillMonitoring();
+    }
+    async nudge(direction, amount = 0.1) {
+        if (!this.state) {
+            throw new Error('No active session');
+        }
+        const sign = direction === 'calmer' ? -1 : 1;
+        const policy = this.state.policy;
+        const previousPolicy = policy;
+        const previousQueue = [...this.state.queuedTracks];
+        // Update soft weights
+        const currentWeights = policy.soft?.weights || {};
+        const newWeights = { ...currentWeights };
+        // Adjust energy and valence — clamp to protocol range [-1, 1]
+        if (typeof newWeights.energy === 'number') {
+            newWeights.energy = clamp(newWeights.energy + sign * amount, -1, 1);
+        }
+        else {
+            newWeights.energy = clamp(0.5 + sign * amount, -1, 1);
+        }
+        if (typeof newWeights.valence === 'number') {
+            newWeights.valence = clamp(newWeights.valence + sign * amount * 0.5, -1, 1);
+        }
+        else {
+            newWeights.valence = clamp(0.5 + sign * amount * 0.5, -1, 1);
+        }
+        // Update policy
+        this.state.policy = {
+            ...policy,
+            soft: {
+                ...policy.soft,
+                weights: newWeights,
+            },
+        };
+        // Clear queue and refill with new weights
+        this.state.queuedTracks = [];
+        await this.refillQueue();
+        if (this.state.queuedTracks.length === 0) {
+            this.state.policy = previousPolicy;
+            this.state.queuedTracks = previousQueue;
+            throw new Error('Nudge could not refill the queue with the updated session policy.');
+        }
+        await this.store.logEvent('session.nudged', { direction, amount, newWeights }, this.state.id);
+        this.emit({
+            type: 'session.nudged',
+            payload: {
+                sessionId: this.state.id,
+                direction,
+                amount,
+                newWeights,
+            },
+        });
+    }
+    getQueue() {
+        return this.state?.queuedTracks || [];
+    }
+    getState() {
+        return this.state;
+    }
+    async refillQueue() {
+        if (!this.state || this.refilling) {
+            return;
+        }
+        this.refilling = true;
+        try {
+            const policy = this.state.policy;
+            const queuePrefs = policy.queue || {};
+            const targetDepth = queuePrefs.target || 12;
+            const refillThreshold = queuePrefs.refillWhenBelow || 5;
+            const currentDepth = this.state.queuedTracks.length;
+            if (currentDepth >= refillThreshold) {
+                return; // Queue still healthy
+            }
+            const needed = targetDepth - currentDepth;
+            // Fetch candidates via provider
+            const candidates = await fetchCandidates(this.provider, policy.sources || {}, needed * 3, // Fetch 3x needed for filtering
+            this.logger);
+            if (candidates.length === 0) {
+                this.emit({
+                    type: 'error',
+                    payload: { message: 'No candidates found for queue refill' },
+                });
+                return;
+            }
+            // Rank tracks
+            const ranked = await rankTracks(candidates, policy, this.state.history, this.getElapsedMs());
+            // Take top N
+            const topTracks = ranked.slice(0, needed);
+            // Add to playback queue
+            for (const { track } of topTracks) {
+                if (track.uri) {
+                    await this.playback.addToQueue(track.uri, track);
+                }
+            }
+            // Update local queue state
+            this.state.queuedTracks.push(...topTracks.map(r => r.track));
+            // Emit event
+            this.emit({
+                type: 'queue.refilled',
+                payload: {
+                    sessionId: this.state.id,
+                    added: topTracks.length,
+                    queueDepth: this.state.queuedTracks.length,
+                },
+            });
+            await this.store.logEvent('queue.refilled', { added: topTracks.length, queueDepth: this.state.queuedTracks.length }, this.state.id);
+        }
+        catch (error) {
+            this.emit({
+                type: 'error',
+                payload: {
+                    message: error instanceof Error ? error.message : 'Queue refill failed',
+                },
+            });
+        }
+        finally {
+            this.refilling = false;
+        }
+    }
+    // Track when a track finishes (called by daemon monitoring)
+    async recordPlay(track) {
+        if (!this.state) {
+            return;
+        }
+        const record = {
+            trackId: track.id,
+            artistIds: track.artistIds && track.artistIds.length > 0
+                ? track.artistIds
+                : [track.artist],
+            playedAt: Date.now(),
+        };
+        this.state.history.push(record);
+        // Trim history to last 48 hours to prevent unbounded memory growth.
+        // 48h covers the widest repetition limit (repeatTrackWithinDays: 1 = 24h)
+        // plus a generous safety margin.
+        const HISTORY_RETENTION_MS = 48 * 60 * 60 * 1000;
+        const cutoff = Date.now() - HISTORY_RETENTION_MS;
+        if (this.state.history.length > 100) {
+            this.state.history = this.state.history.filter(r => r.playedAt >= cutoff);
+        }
+        this.state.currentTrack = track;
+        // Remove from queue
+        this.state.queuedTracks = this.state.queuedTracks.filter(t => t.id !== track.id);
+        // Emit engine event so the daemon can broadcast to SSE clients
+        this.emit({
+            type: 'track.started',
+            payload: {
+                sessionId: this.state.id,
+                playedAt: record.playedAt,
+                track,
+            },
+        });
+        await this.store.logEvent('track.started', {
+            playedAt: record.playedAt,
+            track,
+        }, this.state.id);
+    }
+    startRefillMonitoring() {
+        if (this.refillInterval !== null) {
+            return;
+        }
+        this.refillInterval = setInterval(() => {
+            this.refillQueue().catch(err => {
+                this.logger.error({ error: err instanceof Error ? err.message : String(err) }, 'Auto-refill failed');
+            });
+        }, this.REFILL_CHECK_INTERVAL_MS);
+    }
+    stopRefillMonitoring() {
+        if (this.refillInterval !== null) {
+            clearInterval(this.refillInterval);
+            this.refillInterval = null;
+        }
+    }
+    emit(event) {
+        try {
+            this.onEvent(event);
+        }
+        catch (error) {
+            this.logger.error({ error: error instanceof Error ? error.message : String(error) }, 'Event callback error');
+        }
+    }
+    getElapsedMs() {
+        return this.state ? Date.now() - this.state.startedAt : 0;
+    }
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+export function createEngine(config) {
+    return new SessionEngineImpl(config);
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/history.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Play history tracking and recency penalty calculation
+ */
+import type { RepetitionLimits } from '@sriinnu/harmon-protocol';
+import type { TrackWithFeatures, PlayRecord } from './types.js';
+/**
+ * Calculate recency penalty (0-1)
+ *
+ * 0 = no penalty, 1 = maximum penalty (completely exclude)
+ *
+ * @param track Track to check
+ * @param history Play history
+ * @param limits Repetition limits from policy
+ * @returns Penalty value 0-1
+ */
+export declare function checkRecencyPenalty(track: TrackWithFeatures, history: PlayRecord[], limits?: RepetitionLimits): number;
+/**
+ * Get tracks played in the last N hours
+ *
+ * @param history Play history
+ * @param hoursAgo Hours to look back
+ * @returns Recent play records
+ */
+export declare function getRecentPlays(history: PlayRecord[], hoursAgo: number): PlayRecord[];
+/**
+ * Get unique artists from history
+ *
+ * @param history Play history
+ * @param hoursAgo Hours to look back
+ * @returns Array of artist IDs
+ */
+export declare function getRecentArtists(history: PlayRecord[], hoursAgo: number): string[];
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,CAAC,EAAE,gBAAgB,GACxB,MAAM,CA+CR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,MAAM,GACf,UAAU,EAAE,CAGd;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,CAWV"}

package/dist/history.js

@@ -0,0 +1,81 @@
+/**
+ * Play history tracking and recency penalty calculation
+ */
+/**
+ * Calculate recency penalty (0-1)
+ *
+ * 0 = no penalty, 1 = maximum penalty (completely exclude)
+ *
+ * @param track Track to check
+ * @param history Play history
+ * @param limits Repetition limits from policy
+ * @returns Penalty value 0-1
+ */
+export function checkRecencyPenalty(track, history, limits) {
+    if (!limits) {
+        return 0;
+    }
+    const now = Date.now();
+    let penalty = 0;
+    // Check track repetition
+    if (limits.repeatTrackWithinDays) {
+        const windowMs = limits.repeatTrackWithinDays * 24 * 60 * 60 * 1000;
+        const recentPlay = history.find(r => r.trackId === track.id && (now - r.playedAt) < windowMs);
+        if (recentPlay) {
+            // Full penalty if played within window
+            penalty = Math.max(penalty, 1.0);
+        }
+    }
+    // Check artist repetition
+    if (limits.repeatArtistWithinHours && penalty < 1.0) {
+        const windowMs = limits.repeatArtistWithinHours * 60 * 60 * 1000;
+        // Find recent plays of same artist
+        const recentArtistPlays = history.filter(r => {
+            const timeSince = now - r.playedAt;
+            if (timeSince >= windowMs)
+                return false;
+            // Use structured artistIds when available, fall back to exact name match
+            return r.artistIds.some(aid => {
+                if (track.artistIds && track.artistIds.length > 0) {
+                    return track.artistIds.includes(aid);
+                }
+                return aid === track.artist;
+            });
+        });
+        if (recentArtistPlays.length > 0) {
+            // Graduated penalty based on how many recent plays
+            const artistPenalty = Math.min(recentArtistPlays.length * 0.3, 0.8);
+            penalty = Math.max(penalty, artistPenalty);
+        }
+    }
+    return penalty;
+}
+/**
+ * Get tracks played in the last N hours
+ *
+ * @param history Play history
+ * @param hoursAgo Hours to look back
+ * @returns Recent play records
+ */
+export function getRecentPlays(history, hoursAgo) {
+    const cutoff = Date.now() - (hoursAgo * 60 * 60 * 1000);
+    return history.filter(r => r.playedAt >= cutoff);
+}
+/**
+ * Get unique artists from history
+ *
+ * @param history Play history
+ * @param hoursAgo Hours to look back
+ * @returns Array of artist IDs
+ */
+export function getRecentArtists(history, hoursAgo) {
+    const recent = getRecentPlays(history, hoursAgo);
+    const artists = new Set();
+    for (const record of recent) {
+        for (const artistId of record.artistIds) {
+            artists.add(artistId);
+        }
+    }
+    return Array.from(artists);
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"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"}