Janady13/feedthejoe / src/core/signal/signals.js

1/** 2 * The signal model. 3 * 4 * TikTok's ranking is not driven by likes. The public record on its recommender 5 * — the Monolith paper and the reporting on the internal "For You" documents — 6 * is consistent on one point: *completion rate* dominates, and explicit 7 * approval (the like) is a weak, late, and biased signal. Watch time relative 8 * to item length is the honest measure of whether attention was actually held. 9 * 10 * This module is the translation of that hierarchy to a reading surface. The 11 * analogue of "watched it to the end" is "dwelled on it for about as long as it 12 * takes to read", which is why COMPLETION is computed as a ratio against an 13 * estimated read time rather than as raw seconds. Raw seconds would simply rank 14 * long items above short ones. 15 * 16 * These weights are the tuning surface. They are constants here, not magic 17 * numbers scattered through the ranker. 18 */ 19 20/** 21 * Signal kinds, ordered by the strength of the evidence they carry. 22 * @readonly 23 * @enum {string} 24 */ 25export const Signal = Object.freeze({ 26 /** Dwell time reached a full estimated read. The dominant positive signal. */ 27 COMPLETION: 'completion', 28 /** Returned to an item already seen. Strong: costly to fake, rarely accidental. */ 29 REWATCH: 'rewatch', 30 /** Copied the link or used the share affordance. Intent to show someone else. */ 31 SHARE: 'share', 32 /** Opened the full piece from the feed card. */ 33 EXPAND: 'expand', 34 /** Explicit save. Weak — deliberate approval is rarer and noisier than attention. */ 35 SAVE: 'save', 36 /** Reached the contact surface from this item. The conversion signal. */ 37 CONTACT: 'contact', 38 /** Scrolled past faster than reading speed permits. The only negative. */ 39 SKIP: 'skip', 40}); 41 42/** 43 * Relative weights. COMPLETION is the unit; everything else is expressed 44 * against it. CONTACT exceeds 1.0 because it is the outcome the whole surface 45 * exists to produce, so an item that precedes it should be strongly reinforced. 46 * 47 * SKIP is negative and deliberately large in magnitude relative to SAVE: on a 48 * feed, disinterest is expressed by scrolling, and a model that can only learn 49 * from positive signals will drift toward whatever it happened to show first. 50 * 51 * @readonly 52 * @type {Readonly<Record<string, number>>} 53 */ 54export const SIGNAL_WEIGHT = Object.freeze({ 55 [Signal.COMPLETION]: 1.0, 56 [Signal.REWATCH]: 0.85, 57 [Signal.SHARE]: 0.7, 58 [Signal.EXPAND]: 0.55, 59 [Signal.SAVE]: 0.35, 60 [Signal.CONTACT]: 1.2, 61 [Signal.SKIP]: -0.6, 62}); 63 64/** Words per minute used to estimate a read. Deliberately conservative. */ 65export const READ_WPM = 240; 66 67/** 68 * Estimated seconds to read a piece of the given length. 69 * Floors at 3s so that a one-line item cannot be "completed" by a glance. 70 * 71 * @param {number} wordCount 72 * @returns {number} Seconds. 73 */ 74export function estimatedReadSeconds(wordCount) { 75 if (!Number.isFinite(wordCount) || wordCount <= 0) return 3; 76 return Math.max(3, (wordCount / READ_WPM) * 60); 77} 78 79/** 80 * Convert observed dwell into a completion ratio in [0, 1]. 81 * 82 * Capped at 1: lingering for five times the read length is not five times the 83 * evidence, it usually means the tab was left open. That cap is what stops 84 * "walked away from the laptop" from becoming the strongest signal in the 85 * system. 86 * 87 * @param {number} dwellSeconds 88 * @param {number} wordCount 89 * @returns {number} 90 */ 91export function completionRatio(dwellSeconds, wordCount) { 92 if (!Number.isFinite(dwellSeconds) || dwellSeconds <= 0) return 0; 93 return Math.min(1, dwellSeconds / estimatedReadSeconds(wordCount)); 94} 95 96/** 97 * Resolve an observed event into a scalar learning weight. 98 * 99 * COMPLETION is scaled by how much of the item was actually consumed; every 100 * other signal is discrete and carries its full weight. An unknown kind 101 * contributes nothing rather than throwing — the ranker must never be taken 102 * down by an unrecognised event from the DOM layer. 103 * 104 * @param {{kind: string, completion?: number}} event 105 * @returns {number} 106 */ 107export function weightOf(event) { 108 const base = SIGNAL_WEIGHT[event.kind]; 109 if (base === undefined) return 0; 110 if (event.kind === Signal.COMPLETION) { 111 const ratio = Number.isFinite(event.completion) ? Math.min(1, Math.max(0, event.completion)) : 0; 112 return base * ratio; 113 } 114 return base; 115} 116