muzick/vibe-v2-spec.md

Vibe v2 — Session Director Specification

Status and purpose

This is the target specification for Vibe v2. It turns Vibe from a recommendation queue into a session director: an autonomous system that continuously composes the listener's next hour of music.

The unit of optimisation is not the next track. It is a listening experience that remains coherent, fresh, and rewarding over hours and continues to feel new tomorrow.

This document supplements docs/architecture/09-recommendation-and-identity-v2.md. Where the two documents conflict, this document controls the Session Director and Vibe playback contract.

Product contract

Vibe must feel like a thoughtful radio DJ:

• It plays familiar music, adjacent music, and worthwhile discoveries in a deliberate balance.

• It responds to a skip, full listen, or explicit action quickly enough that the listener can perceive the change.

• It does not collapse into a few favourite artists, genres, languages, decades, labels, producers, or audio-feature bands.

• It has a direction: energy, novelty, and intensity can evolve, but should not jump without a reason.

• It returns to ideas introduced earlier (callbacks) and makes room for surprises.

• It remembers prior sessions sufficiently to avoid replaying yesterday's shape, not merely yesterday's tracks.

  durable history + live feedback + context | v listener state | v candidate retrieval and expansion | v sequence planner / constraint engine | v revisable next 20–50 tracks | v playback | +------------ feedback and replan ------------+

Vibe is not a saved playlist. A client may display a small, revisable preview of the future, but the server owns the authoritative plan and may rewrite every unplayed item at any time.

Goals and non-goals

Goals

1. Maximise expected session reward, not click-through rate or immediate predicted enjoyment alone.
2. Make recommendations conditional on current state, listening context, and the already-played portion of the session.
3. Balance comfort, discovery, diversity, coherence, freshness, and long-term learning while penalising fatigue, repetition, and predictability.
4. Support a self-hosted local library first. Probation tracks are candidates only when their audio is available locally and acquisition policy permits it.
5. Remain useful with sparse metadata. Missing attributes reduce confidence; they must never silently become a hard negative.
6. Be explainable: every selected item has provenance, a reason for its slot, and the constraints that affected it.

Non-goals

• Do not acquire copyrighted audio or bypass existing acquisition gates.
• Do not infer sensitive personal attributes. Context is opt-in and coarse (for example home, work, walking), never precise location.
• Do not treat a permanently fixed exploration ratio, genre quota, or score weight as the final design. Defaults are bootstraps, not truth.
• Do not expose internal goals in a way that makes the experience feel manipulative. Explanations remain human-scale.

---

1. System model

1.1 Inputs

Input	Examples	Role
Permanent taste	favourite artists, genre affinity, negative feedback	Establishes the comfort zone
Multi-horizon memory	30 minutes, 7 days, 3 months, lifetime	Separates current obsession from durable taste
Current session	played/queued tracks, skips, callbacks, budget spend	Determines what fits now
Context	hour, weekday, device, activity, coarse location, optional weather	Changes interpretation of taste
Music knowledge	graph claims, metadata, audio features, embeddings, quality	Retrieves and describes candidates

1.2 Optimisation objective

For sequence q = [t1, …, tn], optimise discounted sequence reward rather than independently sorting tracks:

J(q | state) = sum over i of gamma^i × (
    enjoyment(ti)
  + discovery_value(ti)
  + transition_quality(ti-1, ti)
  + freshness(ti)
  + diversity_gain(q through i)
  + goal_progress(ti)
  - fatigue(ti)
  - repetition(ti, q through i)
  - predictability(q through i)
  - disruption(ti-1, ti)
)

Hard safety and availability constraints apply before optimisation. Gamma discounts distant slots so the director is decisive about the next few tracks without pretending it knows the exact state 40 tracks later.

Initial weights may be hand-tuned, but must be versioned policy configuration. They become learnable only after sufficient reliable events exist.

1.3 Planning horizon

• Keep an internal horizon of 20–50 tracks, chosen from track duration and session conditions.
• Publish only 3–8 tracks to the client as a mutable preview.
• Treat only the immediate next track as committed.
• Replan after every material event and before the preview falls below three playable tracks.
• Do not send duplicate tracks in one Vibe session unless repeat-one was explicitly requested.

---

2. Durable session model

2.1 Session identity

Every Vibe request, playback event, plan version, and feedback event MUST be keyed by session_id and user_id. play_history.batch_id is not a session ID and must not be used as one.

Sessions end explicitly, after configurable inactivity, or when a new Vibe session replaces the current one. A session can resume in a short grace period without losing state or goals.

2.2 Session context

Context is optional, versioned, and privacy-preserving.

interface VibeContext {
  timeZone?: string;
  localHour?: number;  // normally server-derived
  weekday?: number;    // normally server-derived
  dayKind?: 'weekday' | 'weekend' | 'holiday';
  device?: 'desktop' | 'phone' | 'speaker' | 'car' | 'headphones';
  activity?: 'focus' | 'relax' | 'walking' | 'workout' | 'social' | 'unknown';
  locationCategory?: 'home' | 'work' | 'gym' | 'travel' | 'unknown';
  weather?: 'clear' | 'rain' | 'snow' | 'hot' | 'cold' | 'unknown';
  source?: 'current_track' | 'artist' | 'genre' | 'surprise' | 'resume';
}

The frontend must provide an unobtrusive activity/context selector, beginning with activity and device. Browser context is a hint and is never required.

2.3 Event ledger

Store immutable events before updating derived state. This makes feedback auditable, supports offline evaluation, and prevents listener state being the only record of why a plan changed.

CREATE TABLE vibe_sessions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL,
  status TEXT NOT NULL CHECK (status IN
    ('active','paused','ended','expired','replaced')),
  seed_track_id UUID REFERENCES tracks(id) ON DELETE SET NULL,
  context JSONB NOT NULL DEFAULT '{}'::jsonb,
  policy_version TEXT NOT NULL,
  started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  last_event_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  ended_at TIMESTAMPTZ
);

CREATE TABLE vibe_events (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  client_event_id UUID,
  session_id UUID NOT NULL REFERENCES vibe_sessions(id) ON DELETE CASCADE,
  user_id UUID NOT NULL,
  track_id UUID REFERENCES tracks(id) ON DELETE SET NULL,
  type TEXT NOT NULL,
  occurred_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  position_ms INTEGER,
  duration_ms INTEGER,
  payload JSONB NOT NULL DEFAULT '{}'::jsonb,
  UNIQUE (session_id, client_event_id)
);

CREATE TABLE vibe_plan_versions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id UUID NOT NULL REFERENCES vibe_sessions(id) ON DELETE CASCADE,
  version INTEGER NOT NULL,
  reason TEXT NOT NULL,
  state_snapshot JSONB NOT NULL,
  objective_snapshot JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE (session_id, version)
);

CREATE TABLE vibe_plan_items (
  plan_version_id UUID NOT NULL REFERENCES vibe_plan_versions(id) ON DELETE CASCADE,
  ordinal INTEGER NOT NULL,
  track_id UUID NOT NULL REFERENCES tracks(id) ON DELETE CASCADE,
  slot_role TEXT,
  candidate_source TEXT NOT NULL,
  score REAL NOT NULL,
  score_breakdown JSONB NOT NULL,
  explanation JSONB NOT NULL,
  committed BOOLEAN NOT NULL DEFAULT false,
  PRIMARY KEY (plan_version_id, ordinal),
  UNIQUE (plan_version_id, track_id)
);

Create indexes on vibe_sessions(user_id, last_event_at DESC), vibe_events(session_id, occurred_at), and vibe_events(user_id, occurred_at DESC).

Initial event types:

session_started, session_resumed, session_ended, context_changed,
plan_published, track_served, playback_started, progress,
completed, skipped, disliked, kept, favourite_added, queue_removed,
manual_search, album_opened, artist_opened, playlist_added,
track_replayed, volume_changed, playback_error

Event writes must be idempotent. The client supplies client_event_id for any action that might be retried after a network failure.

2.4 Derived listener state

session_state is a cache derived from events and recent history, not the sole source of truth. It must be rebuildable.

interface ListenerSessionState {
  sessionId: string;
  updatedAt: string;
  ageMin: number;

  energy: number;
  valence: number | null;
  focus: number | null;
  attention: number | null;
  cognitiveLoad: number | null;
  emotionalIntensity: number | null;
  noveltyHunger: number;
  noveltyTolerance: number;
  danceabilityTarget: number | null;
  acousticnessTarget: number | null;
  instrumentalnessTarget: number | null;
  vocalPreference: 'vocal' | 'instrumental' | 'mixed';
  tempoTarget: number | null;
  moodTags: Array<{ tag: string; weight: number }>;

  explorationCoefficient: number;
  discoveryRadius: number;
  entropyTarget: number;
  currentArc: ArcInstance;
  activeGoals: SessionGoal[];
  callbackLedger: CallbackToken[];
  fatigue: FatigueSnapshot;
  budgetSpend: BudgetSpendSnapshot;
  recent: RecentSessionSummary;
}

Every inferred value carries confidence and source. Low confidence causes broader, safer choices; it never means the value is zero.

2.5 State update rules

• Completion shifts continuous state modestly toward reliable track features, weighted by listen ratio and feature confidence.
• A quick skip is negative evidence for the track and recommendation route; it is not automatically a dislike of every artist/genre/feature on the track.
• A saved discovery or intentional replay is strong evidence for exploration at that distance and source.
• Repeated unfamiliar skips shrink exploration temporarily; repeated unfamiliar completions expand it gradually.
• Context changes may reset desired trajectory while retaining fatigue and long-term memory.
• Updates MUST be ordered per session. Concurrent feedback must be serialized or use a session-version compare-and-swap.

---

3. Memory horizons and listener model

The listener has independent memories, each with its own decay and purpose.

Horizon	Window	Captures	Primary effect
Immediate	30 minutes	current direction, skips, active fatigue	transitions and next slots
Session	session lifetime	arc, budgets, callbacks, served tracks	sequence planning
Daily	24 hours	today’s exposure and shape	fatigue and fresh starts
Weekly	7 days	recent obsessions and routines	variety across days
Medium	3 months	stable recent taste	affinity and discovery neighbourhood
Lifetime	slow decay	durable favourites and familiar anchors	comfort candidates

Existing long-term, obsession, discovery, negative, forgotten, and contextual belief profiles remain useful. Vibe adds a session layer; it does not flatten all profiles into one taste score.

3.1 Session similarity memory

After each session, generate a compact fingerprint:

interface SessionFingerprint {
  artistDistribution: Record<string, number>;
  genreDistribution: Record<string, number>;
  languageDistribution: Record<string, number>;
  decadeDistribution: Record<string, number>;
  audioTrajectory: Array<{ energy: number; tempo?: number; valence?: number }>;
  discoveryRate: number;
  generatorDistribution: Record<string, number>;
  acceptedDiscoveries: string[];
  durationMin: number;
}

At the next session start, softly penalise similarity to recent fingerprints, especially one or two days ago. An explicit artist/album/genre seed may intentionally override this penalty.

---

4. Music representation and candidate retrieval

4.1 Feature completeness

Each playable track should expose, when available:

• main/featured artists, album, label, producers, composers, scenes;
• genres and tags with confidence;
• release year/decade, language, vocal/instrumental classification;
• BPM, key, energy, valence, danceability, acousticness, instrumentalness, liveness, loudness, duration;
• live version, cover, remix, soundtrack, and side-project relationships;
• quality, availability, and feature-completeness indicators.

Missing audio analysis is unknown, never low energy or instrumental.

4.2 Embeddings and discovery radius

The long-term target is a shared semantic space for tracks, artists, albums, genres, sessions, and listener/context representation. It may begin with feature-derived vectors and later use learned embeddings. Recommended dimensions are 768 or 1024. Musical, lyrical, collaborative, and contextual vectors can be blended at retrieval time.

Distance	Interpretation
0.00	already familiar/favourite
0.15	same artist or tightly associated artist
0.30	strongly similar artist/sound
0.45	different artist in a known style
0.65	adjacent genre or scene
0.90	surprising but explainable

discoveryRadius is a range, not a switch. Sequences normally move through adjacent distances and return to an anchor. Large jumps need a surprise slot or listener reinforcement.

4.3 Candidate pools

Generate independently, retain all provenance, deduplicate by track and canonical identity, then rank.

Pool	Default share	Purpose
Familiar/favourites	30%	comfort and callbacks
Similar tracks/artists	20%	continuity
User-niche recent/trending	15%	timely relevant discovery
Long-tail discovery	10%	avoid popularity collapse
Contextual candidates	10%	fit activity/time
Artist/graph traversal	10%	explainable adjacency
Controlled serendipity	5%	bounded surprise

These are retrieval targets, not mandatory final-plan shares. Allocation adapts to exploration, candidate availability, fatigue, and the active arc.

Required generator classes:

1. Comfort: favourites and trusted artists with fatigue suppression.
2. Adjacent: graph/ANN neighbours of recent successes/current trajectory.
3. Discovery: unfamiliar artists at a safe distance with credible graph path.
4. Revival: forgotten favourites, old obsessions, accepted tracks after rest.
5. Deep dive: album/obsession exploration limited by album/artist budgets.
6. Contextual: candidates with comparable activity, hour, or device evidence.
7. Freshness: new releases/niche trends fitting the listener graph.
8. Serendipity: deliberately bounded unexplored route, never random catalogue.

Candidate provenance retains every nominating path, not just the winning source. It is required for explanations and source-level learning.

---

5. Fatigue, repetition, and diversity

5.1 Fatigue principle

Everything can fatigue; everything recovers. Fatigue is decayed exposure, not a permanent ban.

fatigue(dimension, entity, now) =
  min(1, sum of exposure_weight(event) × exp(-event_age / tau_dimension))

Exposure weight is higher for completion, lower for a short sample, and zero for playback failure. Tau is configurable per dimension and may be adapted from observed tolerance.

Track fatigue must blend multiple windows: today, yesterday, week, and month. It must not be a single recent-history query.

5.2 Required fatigue dimensions

Dimension	Example	Planner action
Track	heard today/replayed yesterday	strong suppression unless requested
Artist/canonical identity	12 tracks by one artist	widen artist pool
Album	half an album played	spread across hours/days
Genre/scene	18 metal tracks	move to adjacent style
Language	35 Japanese tracks	mix another language/instrumental
Vocal/instrumentation	all vocal, same vocal type	alternate texture
Tempo/energy/valence	narrow BPM/mood band	controlled transition
Producer/label	repeated creative lineage	force new route
Decade	all recent releases	reintroduce another era
Recommendation route	same graph edge repeatedly	diversify path

Unknown metadata may not claim to satisfy a specific quota.

5.3 Repetition rules

Hard rules, unless explicitly overridden:

• A served track never reappears in one Vibe session.
• A track in its configured recent window is ineligible.
• No more than two tracks by a canonical artist in 20 tracks.
• No more than three tracks from an album in 40 tracks.
• Skipped/disliked tracks are ineligible for the rest of the session.

Soft, adaptive minimum distances apply to artist, album, genre, language, producer, and energy band. If the pool is too small, relax the least important soft constraint, record it, and never silently relax hard track exclusion.

5.4 Diversity budgets

Budgets are planner resources, not passive analytics. Initial defaults:

Dimension	Target	Horizon
Any artist	at most 20%	30 min
Any genre	at most 40%	30 min
Any language	at most 60%	30 min
Instrumental	at least 10% if inventory permits	30 min
New artists	about 15%	60 min
Familiar favourites	about 25%	60 min

Budgets may be upper bounds, lower bounds, or target ranges. The planner projects spend across the proposed sequence, not only completed history.

Explicit user intent may temporarily override soft targets. Starting an album or repeatedly selecting an artist narrows the session intentionally; diversity prevents accidental loops, not explicit choice.

5.5 Anti-loop detector

Run after every state update and every plan proposal. Detect concentration across artist/canonical identity, album, genre, scene, label, producer, language, decade, BPM, energy, valence, vocal type, candidate source, and graph path.

Use HHI and Shannon entropy accurately; HHI must not be called entropy. Correct the detected dimension directly:

Loop	Required correction
Artist/album	retrieve other artists; reserve only later callback
Genre/scene	retrieve adjacent genres at compatible energy
Language/vocal	reserve next eligible alternate slot
Tempo/energy	alter next arc target gradually
Producer/label/route	exclude repeated relationship from retrieval
Low route diversity	require another generator/path

Do not merely boost an already available experimental candidate if it does not fix the detected loop.

---

6. Arcs, callbacks, surprise, and long-term rhythm

6.1 Arc templates

An arc is desired trajectory plus slot roles and transition tolerance, not just a generator list.

Arc	Example trajectory
Comfort	known → known → adjacent → favourite
Discovery	favourite → similar → new → familiar callback
Energetic	medium → high → peak → cooldown
Late-night	soft → ambient → acoustic → slow electronic
Focus	instrumental/low-vocal → steady complexity → gentle reset
Album exploration	familiar anchor → album chapter → relief → callback

Slots define target ranges/deltas for energy, tempo, valence, acousticness, instrumentality, novelty distance, and familiarity. Missing features reduce confidence rather than reject a candidate.

Arc selection depends on state, context, age, explicit intent, and weekly schedule. It changes only when feedback/context makes the current arc implausible.

6.2 Transition model

For every pair, compute transition quality from:

• tempo delta and beat compatibility where reliable;
• harmonic/key compatibility where available;
• energy, valence, acousticness, danceability, instrumentality deltas;
• genre/scene continuity or an explainable bridge;
• artist/album separation;
• language and vocal contrast when fatigue calls for it;
• novelty-distance progression; and
• current arc fit.

A good transition is not always similarity. A cooldown after a peak or a surprise after an anchor is good if it fits the arc.

6.3 Callbacks

A callback token is created when an artist, genre, energy peak, theme, or favourite is worth revisiting. It has minimum/maximum separation and cannot violate fatigue/repetition rules.

favourite → new artist → adjacent artist → callback to favourite
heavy → soft bridge → different heavy track
forgotten favourite → side project → return to old era

Callbacks are optional and must never become repetition.

6.4 Surprise budget

Every sustained session needs bounded surprise. Attempt at least one eligible, explainable surprise per hour when inventory permits. Types include forgotten favourite, live/acoustic/cover/remix, producer/side project, old obsession, soundtrack connection, and novel graph route.

A surprise is paired with a recovery anchor. A quick skip lowers propensity for that surprise type, not the listener’s whole taste profile.

6.5 Invisible goals

Goals are durable, bounded, and never override hard constraints or explicit direction. Examples:

• complete an album over several days without a block;

• introduce a promising artist gradually;

• revisit a favourite monthly after recovery;

• balance languages/decades over a week;

• rotate producer/scene routes;

• evaluate a probation discovery;

• preserve a surprise opportunity per hour.

  CREATE TABLE vibe_goals ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id UUID NOT NULL, type TEXT NOT NULL, entity_type TEXT, entity_id UUID, state JSONB NOT NULL DEFAULT '{}'::jsonb, priority REAL NOT NULL DEFAULT 0.5, status TEXT NOT NULL CHECK (status IN ('active','paused','complete','expired')), created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), due_at TIMESTAMPTZ, completed_at TIMESTAMPTZ );

6.6 Weekly rhythm

Vibe may use an opt-in weak weekly prior: Monday discoveries, Tuesday album exploration, Wednesday comfort, Thursday forgotten favourites, Friday high energy, weekend broad/context-led mix. It must never override explicit intent or current context.

---

7. Candidate ranking and sequence planning

7.1 Candidate proposal score

candidate_score =
    w_affinity × personal_affinity
  + w_session × session_state_fit
  + w_transition × transition_fit_from_previous
  + w_discovery × discovery_value
  + w_freshness × freshness
  + w_quality × track_quality
  + w_goal × goal_progress
  - w_fatigue × fatigue_penalty
  - w_repeat × repetition_penalty
  - w_saturation × dimension_saturation
  - w_risk × unsupported_metadata_or_route_risk

This is a proposal score, not final selection. Persist normalised, policy-versioned score breakdown with every selected plan item.

7.2 Constraint engine

Apply constraints during sequence construction:

1. Exclude unavailable, hidden, retired, served, and blocked tracks.
2. Enforce hard repetition/safety constraints.
3. Satisfy arc slot requirements.
4. Project budgets across the horizon.
5. Penalise session similarity and path concentration.
6. Reserve callback, discovery, and surprise opportunities.
7. Select the highest-value feasible sequence.

If no feasible sequence exists, return a degraded plan with structured constraint_relaxations. Relax soft diversity targets, then arc precision, then freshness. Never reintroduce an explicitly disliked or served track simply to fill the plan.

7.3 Planner algorithm

Initial implementation is constrained beam search:

• retrieve about 500–2,000 deduplicated candidates;
• keep beam width 20–50 with incremental objective and projected state;
• expand only compatible candidates per slot;
• plan 20–50 slots; commit first; publish preview only;
• replan from current state after feedback while preserving committed track and still-valid callback/goal tokens.

Later options include MCTS, transformer decoding, or model-predictive control. The planner interface must stay algorithm-agnostic.

7.4 Controlled unpredictability

Measure predictability over recent and proposed sequence using artist, genre, source/path, novelty distance, and feature distributions.

• Too predictable: allocate adjacent/surprise candidate and protect a later comfort callback.
• Too chaotic: shrink discovery radius and inject a familiar anchor.

The target is intentional surprise, neither randomness nor maximum familiarity.

---

8. Feedback and learning

8.1 Feedback interpretation

Signal	Interpretation	Immediate action
Skip under 5 sec	strong mismatch	remove route/track, reduce local risk, replan
Skip under 20 sec	mismatch	penalise candidate/path, replan
Late skip	weak negative/transition issue	modest penalty
Completion	weak positive	update state/affinity modestly
Replay	strong positive	reinforce affinity and comfort
Keep/favourite	strong positive	reinforce entities and route
Playlist add/share	very strong positive	reinforce strongly
Mute/hide artist/genre	strong negative	exclude or suppress
Manual search/open album	intent evidence	bias session appropriately
Volume change	weak/noisy evidence	aggregate with other signals
Session abandonment	delayed negative reward	evaluate preceding sequence

Completion uses actual position and duration. Long intros must not be treated exactly like short tracks.

8.2 Dynamic exploration

Maintain exploration coefficient E in range 0–1 and discovery radius.

quick skip of unfamiliar track       E -= 0.05
completion of unfamiliar track       E += 0.03
save/favourite unknown artist        E += 0.12
repeated known completion            E -= 0.01 only if comfort over budget
explicit more-discovery control      bounded immediate increase

Clamp and smooth updates so one event does not whiplash a session. Persist the evidence. play_of_never_seen or equivalent MUST be emitted by production playback; a read-only schema capability is not a feature.

8.3 Learning rollout

1. Ship deterministic rules with complete event and plan logging.
2. Replay historical sessions for offline evaluation.
3. Use contextual bandits for calibrated immediate/short-horizon weights and generator routing under safety limits.
4. Consider offline RL/model-based sequence policy only after reliable off-policy evaluation exists.

Retain deterministic fallback and a kill switch for learned policy.

---

9. API and frontend contract

9.1 Start/resume

POST /api/v2/vibe/sessions

{
  "seedTrackId": "uuid or optional",
  "context": { "activity": "focus", "device": "headphones" },
  "intent": "optional mode",
  "resumeSessionId": "uuid or optional"
}

Response includes sessionId, planVersion, now, revisable preview, and concise state summary. User identity comes from authenticated/trusted request context, not a silent shared default UUID.

9.2 Playback event

POST /api/v2/vibe/sessions/:sessionId/events

{
  "eventId": "client UUID",
  "type": "progress | completed | skipped | kept | disliked | ...",
  "trackId": "uuid",
  "positionMs": 12500,
  "durationMs": 203000,
  "payload": {}
}

Response includes canonical planVersion, replacement preview, state summary, and replan reason.

The client MUST reconcile its unplayed Vibe buffer whenever replacement preview is returned. It must not keep playing stale prefetched items only because they were fetched before feedback. The currently loaded track is not interrupted unless the listener explicitly skips it.

9.3 Serve next

POST /api/v2/vibe/sessions/:sessionId/next
{ "expectedPlanVersion": 4 }

The response is idempotent for request/plan version and marks the item served. If a newer plan exists, return that preview instead of a stale track.

9.4 UI requirements

• Present Vibe as an evolving session, not static playlist.
• Show concise direction such as gentle discovery or late-night cooldown.
• Preview only revisable next tracks and label them adaptive.
• Offer Keep, Dislike, Skip, End, plus implicit progress tracking.
• Offer lightweight context and more-familiar/more-discovery controls.
• Explain a track on demand with provenance and human-readable reason.
• Do not let ordinary library actions accidentally write Vibe feedback.
• Preserve session identity through navigation and recover after transient network failure.

---

10. Operational requirements

10.1 Consistency and concurrency

• Serialize plan mutation per session.
• Use monotonic planVersion and client optimistic concurrency.
• Redis may cache active plans; Postgres event/plan records are authoritative. Redis expiry must never erase only session history.
• Stale-session reaper ends inactive sessions and creates final fingerprint; it never deletes listener history.
• Revalidate track state and availability immediately before serving.

10.2 Performance

• Candidate retrieval p95 under 250 ms for warm local catalogue.
• Replan p95 under 750 ms for a 20-track baseline horizon.
• Serve-next p95 under 150 ms when valid plan exists.
• If ANN, external metadata, or context is unavailable, fall back to local graph/metadata/favourites and record degraded source state.

10.3 Observability

Log/measure per policy version and session:

• candidate counts/rejection reasons per generator;
• metadata coverage;
• constraint violations and relaxations;
• replan latency/reason;
• client stale-preview replacement success;
• fatigue/budget/entropy trajectories;
• discovery source/distance acceptance;
• session outcome metrics.

Never log raw precise location or unnecessary personal context.

---

11. Success metrics

Primary metrics:

• average uninterrupted listening duration;
• completed-session duration and return probability;
• discovery acceptance by distance/source;
• new artists saved/favourited;
• playlist additions and intentional replays;
• perceived freshness;
• artist/genre/language/path diversity and repetition rate;
• sessions with a successful surprise and healthy comfort anchor.

Secondary diagnostics:

• quick/medium skips, hides, abandonments;
• plan replacement latency;
• no-eligible-candidate rate;
• metadata coverage/fallback frequency;
• hard-constraint satisfaction;
• similarity to recent sessions.

CTR is diagnostic only. It must not become the objective that causes favourite-artist loops.

---

12. Delivery phases and acceptance criteria

Phase 0 — Correct session contract

Deliver durable sessions/events/versioned plans, session IDs on all playback events, and client replacement of unplayed preview after replan.

Acceptance:

• A quick skip changes unplayed preview within one successful event round trip.
• Completion/skip cannot be attributed to another session.
• Backend restart does not lose event history or plan audit.

Phase 1 — Enforced fatigue and diversity

Wire every budget/fatigue dimension used by policy into construction. Add album, language, vocal/instrumental, and route controls.

Acceptance:

• Fixtures prove artist, album, genre, language, and track constraints.
• Changing a budget changes the plan, not only debug output.
• Anti-loop response corrects the detected dimension.

Phase 2 — Musical arcs and sequence planner

Add feature access, transition scoring, callbacks, surprise tokens, constrained beam search.

Acceptance:

• Energetic arc rises then cools within tolerance when features exist.
• Discovery arc anchors a discovery between familiar items.
• Chosen plans beat greedy order on offline fixture objective.

Phase 3 — Context, long-term goals, session memory

Add context capture, fingerprints, weekly priors, and scheduling.

Acceptance:

• Context affects ranking only with comparable evidence; otherwise fallback is safe.
• Consecutive unseeded sessions are less similar than baseline without reducing completion rate.
• Album/artist goals spread exposure across sessions.

Phase 4 — Dynamic exploration and learning

Emit complete feedback, calibrate radius, add offline evaluation, then guarded online learning.

Acceptance:

• Unknown-track completion/skip changes exploration in expected bounded direction.
• Learned decisions have policy version, feature log, and fallback.
• No rollout proceeds without offline and guardrail metrics.

Phase 5 — Embeddings and world model

Introduce ANN retrieval and, only when data quality warrants it, learn:

listener_state(t) + selected_track -> listener_state(t + 1)

The controller can then select tracks partly for the state they create, not only immediate affinity. This phase is optional and never blocks the deterministic director.

---

13. Test matrix

Scenario	Required assertion
Fast skip of unknown	preview replaced; radius shrinks; track excluded
Accepted discovery	radius grows; source receives positive attribution
Artist loop	cap respected; compatible bridge used
Language fatigue	alternate language/instrumental appears if available
Album deep dive	tracks spread; no accidental completion block
Low entropy	explainable diversity plus familiar anchor
High entropy	comfort inserted without favourite collapse
Context change	new preview without losing fatigue history
Redis loss	durable event/plan restores coherent preview
Sparse metadata	safe plan and reduced-confidence record
Explicit artist intent	soft diversity may yield; served tracks never repeat
Long session	no served duplicate; callbacks/surprise/budgets bounded

Use deterministic catalogue fixtures with known artists, albums, languages, audio features, and graph routes. Test resulting sequences, not merely whether a candidate list was sorted.

Final product definition

Vibe succeeds when a listener can spend six hours with it and feel it understood both their taste and their moment: it mixed comfort with meaningful discovery, maintained a coherent evolving arc, avoided fatigue and obvious loops, made memorable returns, and still left tomorrow feeling fresh.