Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

14.4 KB
Raw Blame
/**
 * Pure-logic tests for twin enrichment (Phase 7, #2156). No DB, no provider
 * calls — these cover the deterministic rollup math, novelty ratio, hourly
 * histogram bucketing (with timezone edge cases), observed-chronotype
 * classification, and the stated-vs-observed comparison (divergence is signal,
 * observed never clobbers stated). The DB fetch + file persistence + LLM
 * interpretation paths are thin wrappers over these helpers.
 */
import { describe, it, expect } from 'vitest';
import {
  topCounts,
  noveltyRatio,
  listenArtistNames,
  listenTrackEntries,
  listenGenreNames,
  topTrackCounts,
  rollupListen,
  rollupWatch,
  chronotypeHistogram,
  peakHour,
  classifyObservedChronotype,
  compareChronotype,
  buildConsumptionBrief,
} from './twinEnrichment.js';

describe('topCounts', () => {
  it('counts and sorts by frequency, then alphabetically for ties', () => {
    const out = topCounts(['b', 'a', 'b', 'c', 'a', 'a']);
    expect(out).toEqual([
      { name: 'a', count: 3 },
      { name: 'b', count: 2 },
      { name: 'c', count: 1 },
    ]);
  });
  it('skips blank/nullish keys and trims', () => {
    expect(topCounts([' x ', '', null, undefined, 'x'])).toEqual([{ name: 'x', count: 2 }]);
  });
  it('respects the limit', () => {
    expect(topCounts(['a', 'b', 'c', 'd'], 2)).toHaveLength(2);
  });
  it('breaks equal-count ties by name (stable federation order)', () => {
    // z and a both appear once — alphabetical keeps checksums convergent.
    expect(topCounts(['z', 'a']).map((x) => x.name)).toEqual(['a', 'z']);
  });
});

describe('noveltyRatio', () => {
  it('returns null ratio for an empty window (no signal ≠ 0% novel)', () => {
    expect(noveltyRatio([])).toEqual({ total: 0, distinct: 0, repeats: 0, noveltyRatio: null });
  });
  it('is 1.0 when nothing repeats', () => {
    expect(noveltyRatio(['a', 'b', 'c'])).toEqual({ total: 3, distinct: 3, repeats: 0, noveltyRatio: 1 });
  });
  it('drops as items repeat', () => {
    // 4 plays, 2 distinct → 0.5 novel, 2 repeats.
    expect(noveltyRatio(['a', 'a', 'b', 'b'])).toEqual({ total: 4, distinct: 2, repeats: 2, noveltyRatio: 0.5 });
  });
});

describe('listenArtistNames / listenGenreNames', () => {
  it('reads structured artist objects', () => {
    expect(listenArtistNames({ metadata: { artists: [{ name: 'Boards of Canada' }, { name: 'Aphex Twin' }] } }))
      .toEqual(['Boards of Canada', 'Aphex Twin']);
  });
  it('accepts bare-string artists', () => {
    expect(listenArtistNames({ metadata: { artists: ['Solo'] } })).toEqual(['Solo']);
  });
  it('reads the import shape (metadata.artist single string) without leaking the album', () => {
    // spotifyImport stores metadata.artist + a "Artist — Album" summary; the
    // artist tally must be just the artist, never "Artist — Album".
    expect(listenArtistNames({ metadata: { artist: 'Radiohead' }, summary: 'Radiohead — OK Computer' }))
      .toEqual(['Radiohead']);
  });
  it('falls back to the comma-joined summary line when metadata is lean', () => {
    expect(listenArtistNames({ summary: 'A, B , C' })).toEqual(['A', 'B', 'C']);
  });
  it('returns [] when there is nothing usable', () => {
    expect(listenArtistNames({})).toEqual([]);
    expect(listenGenreNames({})).toEqual([]);
  });
  it('reads genres when present (future-proof)', () => {
    expect(listenGenreNames({ metadata: { genres: ['ambient', { name: 'idm' }] } })).toEqual(['ambient', 'idm']);
  });
});

describe('listenTrackEntries / topTrackCounts', () => {
  it('normalizes live Spotify and extended-history track shapes', () => {
    expect(listenTrackEntries({ metadata: { trackName: 'Track A', artists: [{ name: 'Artist A' }] } }))
      .toEqual([{ name: 'Track A', artist: 'Artist A' }]);
    expect(listenTrackEntries({ title: 'Track B', metadata: { artist: 'Artist B', trackUri: 'spotify:track:2' } }))
      .toEqual([{ name: 'Track B', artist: 'Artist B' }]);
    expect(listenTrackEntries({ title: 'Example Episode', metadata: { type: 'episode' } })).toEqual([]);
  });

  it('counts tracks by name and artist with deterministic tie ordering', () => {
    expect(topTrackCounts([
      { name: 'Track B', artist: 'Artist B' },
      { name: 'Track A', artist: 'Artist A' },
      { name: 'Track B', artist: 'Artist B' },
    ])).toEqual([
      { name: 'Track B', artist: 'Artist B', count: 2 },
      { name: 'Track A', artist: 'Artist A', count: 1 },
    ]);
  });
});

describe('rollupListen / rollupWatch', () => {
  const listens = [
    { kind: 'media.listen', title: 'T1', metadata: { trackId: 't1', artists: [{ name: 'A' }], genres: ['ambient'] } },
    { kind: 'media.listen', title: 'T1', metadata: { trackId: 't1', artists: [{ name: 'A' }], genres: ['ambient'] } },
    { kind: 'media.listen', title: 'T2', metadata: { trackId: 't2', artists: [{ name: 'B' }] } },
    { kind: 'media.watch', title: 'V1', metadata: { videoId: 'v1', channel: 'Chan' } }, // ignored by listen rollup
  ];
  it('rolls up only media.listen events', () => {
    const r = rollupListen(listens);
    expect(r.total).toBe(3);
    expect(r.topArtists).toEqual([{ name: 'A', count: 2 }, { name: 'B', count: 1 }]);
    expect(r.topTracks).toEqual([
      { name: 'T1', artist: 'A', count: 2 },
      { name: 'T2', artist: 'B', count: 1 },
    ]);
    expect(r.topGenres).toEqual([{ name: 'ambient', count: 2 }]);
    // 3 plays, t1 twice → 2 distinct.
    expect(r.novelty).toEqual({ total: 3, distinct: 2, repeats: 1, noveltyRatio: 0.667 });
  });
  it('handles imported listens (metadata.artist + trackUri) — artist tally + novelty by uri', () => {
    // Two DIFFERENT tracks that happen to share a title must not collapse as a
    // repeat — novelty keys on trackUri, not the title.
    const imported = [
      { kind: 'media.listen', title: 'Intro', metadata: { artist: 'A', trackUri: 'spotify:track:1' }, summary: 'A — Album1' },
      { kind: 'media.listen', title: 'Intro', metadata: { artist: 'B', trackUri: 'spotify:track:2' }, summary: 'B — Album2' },
      { kind: 'media.listen', title: 'Intro', metadata: { artist: 'A', trackUri: 'spotify:track:1' }, summary: 'A — Album1' },
    ];
    const r = rollupListen(imported);
    expect(r.total).toBe(3);
    expect(r.topArtists).toEqual([{ name: 'A', count: 2 }, { name: 'B', count: 1 }]);
    // 3 plays, 2 distinct URIs → not collapsed by shared title.
    expect(r.novelty).toEqual({ total: 3, distinct: 2, repeats: 1, noveltyRatio: 0.667 });
  });
  it('counts a live trackId and an imported trackUri for the same track as one identity', () => {
    const mixed = [
      { kind: 'media.listen', title: 'Song', metadata: { trackId: 'example123' } },
      { kind: 'media.listen', title: 'Song', metadata: { trackUri: 'spotify:track:example123' } },
      { kind: 'media.listen', title: 'Song', metadata: { trackId: 'other456' } },
      { kind: 'media.listen', title: 'Ep', metadata: { trackUri: 'spotify:episode:example123' } },
      { kind: 'media.listen', title: 'Ep', metadata: { trackId: 'example123', trackUri: 'spotify:episode:example123' } },
    ];
    expect(rollupListen(mixed.slice(0, 2)).novelty).toEqual({ total: 2, distinct: 1, repeats: 1, noveltyRatio: 0.5 });
    // Same title, different id stays distinct; an episode never collides with a track.
    expect(rollupListen(mixed).novelty).toEqual({ total: 5, distinct: 3, repeats: 2, noveltyRatio: 0.6 });
  });
  it('rolls up only media.watch events with channels + novelty', () => {
    const watches = [
      { kind: 'media.watch', title: 'V1', metadata: { videoId: 'v1', channel: 'Chan', topics: ['tech'] } },
      { kind: 'media.watch', title: 'V2', metadata: { videoId: 'v2', channel: 'Chan' } },
      { kind: 'media.listen', title: 'T', metadata: { trackId: 't' } },
    ];
    const r = rollupWatch(watches);
    expect(r.total).toBe(2);
    expect(r.topChannels).toEqual([{ name: 'Chan', count: 2 }]);
    expect(r.topTopics).toEqual([{ name: 'tech', count: 1 }]);
    expect(r.novelty.distinct).toBe(2);
  });
});

describe('chronotypeHistogram — timezone bucketing', () => {
  it('buckets by LOCAL hour, not UTC', () => {
    // 2026-07-04T02:30:00Z = 19:30 the previous day in America/Los_Angeles (-07).
    const events = [{ kind: 'message.sent', happenedAt: '2026-07-04T02:30:00Z' }];
    const hist = chronotypeHistogram(events, 'America/Los_Angeles');
    expect(hist[19].messages).toBe(1);
    expect(hist[19].total).toBe(1);
    // Same instant in UTC lands at hour 2.
    const utc = chronotypeHistogram(events, 'UTC');
    expect(utc[2].messages).toBe(1);
  });
  it('separates categories and counts only outbound messages', () => {
    const events = [
      { kind: 'message.sent', happenedAt: '2026-07-04T15:00:00Z' },
      { kind: 'message.received', happenedAt: '2026-07-04T15:00:00Z' }, // not a self-timing signal
      { kind: 'calendar.event', happenedAt: '2026-07-04T15:00:00Z' },
      { kind: 'media.listen', happenedAt: '2026-07-04T15:00:00Z' },
      { kind: 'media.watch', happenedAt: '2026-07-04T15:00:00Z' },
    ];
    const hist = chronotypeHistogram(events, 'UTC');
    expect(hist[15]).toMatchObject({ messages: 1, meetings: 1, media: 2 });
    // message.received is excluded entirely (reflects others' timing, not the
    // user's) — total is the sum of the three signal categories.
    expect(hist[15].total).toBe(4);
  });
  it('handles a DST spring-forward instant without crashing', () => {
    // 2026-03-08 09:30Z is ~01:30 local before the 02:00 PST→PDT jump.
    const events = [{ kind: 'media.listen', happenedAt: '2026-03-08T09:30:00Z' }];
    const hist = chronotypeHistogram(events, 'America/Los_Angeles');
    const active = hist.filter((s) => s.total > 0);
    expect(active).toHaveLength(1);
    expect(active[0].media).toBe(1);
  });
  it('skips invalid timestamps', () => {
    const hist = chronotypeHistogram([{ kind: 'message.sent', happenedAt: 'nonsense' }], 'UTC');
    expect(hist.every((s) => s.total === 0)).toBe(true);
  });
});

describe('peakHour', () => {
  it('returns the busiest hour for a field, or null when empty', () => {
    const hist = chronotypeHistogram([
      { kind: 'message.sent', happenedAt: '2026-07-04T09:00:00Z' },
      { kind: 'message.sent', happenedAt: '2026-07-04T09:30:00Z' },
      { kind: 'message.sent', happenedAt: '2026-07-04T14:00:00Z' },
    ], 'UTC');
    expect(peakHour(hist, 'messages')).toBe(9);
    expect(peakHour(hist, 'media')).toBe(null);
  });
});

describe('classifyObservedChronotype', () => {
  const at = (hourUtc, kind = 'media.listen') => ({ kind, happenedAt: `2026-07-04T${String(hourUtc).padStart(2, '0')}:00:00Z` });
  it('returns null type below the minimum sample size', () => {
    const hist = chronotypeHistogram([at(9), at(9)], 'UTC');
    expect(classifyObservedChronotype(hist).type).toBe(null);
  });
  it('classifies an early cluster as morning', () => {
    const events = [6, 7, 7, 8, 8, 9].map((h) => at(h));
    const hist = chronotypeHistogram(events, 'UTC');
    expect(classifyObservedChronotype(hist).type).toBe('morning');
  });
  it('classifies a late cluster as evening', () => {
    const events = [18, 19, 20, 20, 21, 22].map((h) => at(h));
    const hist = chronotypeHistogram(events, 'UTC');
    expect(classifyObservedChronotype(hist).type).toBe('evening');
  });
  it('uses a circular mean so a midnight-wrapped night-owl classifies as evening, not morning', () => {
    // Active 22:00–02:00 — a linear mean would land near noon (wrong); the
    // circular mean wraps the center near midnight, and the small-hours band
    // must then read as evening (a night owl), never 'morning'.
    const events = [22, 23, 0, 1, 2, 23].map((h) => at(h));
    const hist = chronotypeHistogram(events, 'UTC');
    const { type, centerHour } = classifyObservedChronotype(hist);
    expect(centerHour).not.toBeGreaterThan(3); // wrapped near midnight, not ~12
    expect(type).toBe('evening');
  });
  it('classifies a small-hours center (night owl) as evening', () => {
    const events = [23, 0, 0, 1, 1, 2].map((h) => at(h));
    const { type } = classifyObservedChronotype(chronotypeHistogram(events, 'UTC'));
    expect(type).toBe('evening');
  });
});

describe('compareChronotype — divergence is signal, not error', () => {
  it('agrees when both match', () => {
    expect(compareChronotype('morning', 'morning')).toMatchObject({ agree: true, divergence: 'none' });
  });
  it('flags adjacent types as mild divergence', () => {
    expect(compareChronotype('morning', 'intermediate')).toMatchObject({ agree: false, divergence: 'mild', distance: 1 });
  });
  it('flags morning-vs-evening as strong divergence', () => {
    expect(compareChronotype('morning', 'evening')).toMatchObject({ agree: false, divergence: 'strong', distance: 2 });
  });
  it('returns unknown (never a false divergence) when a side is missing', () => {
    expect(compareChronotype(null, 'evening')).toMatchObject({ agree: null, divergence: 'unknown' });
    expect(compareChronotype('morning', null)).toMatchObject({ agree: null, divergence: 'unknown' });
  });
});

describe('provenance — observed evidence supplements, never overwrites stated', () => {
  it('observed evidence records carry source: observed and never mutate a stated object', () => {
    // The comparison surfaces both values side by side; the stated value is
    // passed through untouched regardless of what was observed.
    const stated = Object.freeze({ type: 'morning' });
    const cmp = compareChronotype(stated.type, 'evening');
    expect(stated.type).toBe('morning'); // unchanged (frozen would throw on mutation)
    expect(cmp.statedType).toBe('morning');
    expect(cmp.observedType).toBe('evening');
  });
});

describe('buildConsumptionBrief', () => {
  it('renders numbers only — no invented interpretation', () => {
    const taste = {
      windows: {
        month: {
          days: 30,
          listen: { total: 5, topArtists: [{ name: 'A', count: 3 }], topGenres: [], novelty: { noveltyRatio: 0.6, distinct: 3, total: 5 } },
          watch: { total: 2, topChannels: [{ name: 'Chan', count: 2 }], topTopics: [] },
        },
      },
    };
    const chronotype = { observedType: 'evening', centerHour: 20, sampleSize: 40, peakHours: { messages: 21, media: 22, overall: 21 } };
    const brief = buildConsumptionBrief(taste, chronotype);
    expect(brief).toContain('A (3)');
    expect(brief).toContain('Chan (2)');
    expect(brief).toContain('Observed chronotype: evening');
    expect(brief).toContain('Novelty ratio: 0.6');
  });
  it('is safe on empty/absent evidence', () => {
    expect(() => buildConsumptionBrief(null, null)).not.toThrow();
    expect(buildConsumptionBrief(null, null)).toBe('');
  });
});