@logg/signals 0.3.0 → 0.5.0

package/README.md

@@ -522,9 +522,71 @@ Methods shared by both engines: `prime()`, `engage()`, `recommend()`,
 `setOwned()`, `clearSeen()`, `reset()`, `seenCount()`. The dual engine adds
 `setSampleSize(k)` to tune explore vs. exploit.
 
+### Weighted scoring (dual engine) — `0.4.0`
+
+By default `DualBucketRecommender` ranks candidates by the sum of raw slot
+powers, which ignores each feature's schema `weight` and lets a
+low-cardinality feature (e.g. one dominant `category`) outweigh a
+high-cardinality one (e.g. `brand`) purely by accumulated mass. Pass
+`weightedScoring: true` to instead weight each feature by its schema `weight`
+and normalize a value's power to its share of the bucket (an ε-floored share,
+the same scheme the v1 engine uses):
+
+```typescript
+const reco = new DualBucketRecommender(catalog, { schema, weightedScoring: true });
+```
+
+This makes schema weights authoritative and removes the cardinality bias. It
+is **off by default** to preserve existing v2 ranking. Note the scale change:
+with the flag on, `net` / `diagnostics.bestNet` move from unbounded raw power
+to roughly `[−Σweight, +Σweight]` (≈ `[−1, 1]` when weights sum to 1), so any
+consumer comparing `bestNet` against a raw-power threshold must rescale.
+
+### Feed controls (dual engine) — `0.5.0`
+
+Two additive, **default-off** knobs that shape the feed without touching how
+the engine learns:
+
+**`seenWindow`** — a sliding "already shown" FIFO. By default the dual engine
+suppresses every item it has shown until a full-page rotation
+(`shuffleThreshold`), so a large catalog yields an all-distinct feed and
+familiar items rarely recur. Set `seenWindow` to let an item become eligible
+again after N other picks:
+
+```typescript
+const reco = new DualBucketRecommender(catalog, { schema, seenWindow: 300 });
+```
+
+`undefined` / `0` keeps the original behavior. `clearSeen()` / `reset()` clear
+the window.
+
+**`diversityCap`** — cap any single value of one feature from dominating the
+feed. Best-of-K is pure exploit, so the brand with the most inventory + taste
+can swamp the feed. When the top pick's value already holds `maxShare` of the
+recent window, the engine backfills with the best *familiar* under-cap
+candidate instead:
+
+```typescript
+const reco = new DualBucketRecommender(catalog, {
+  schema,
+  diversityCap: { feature: 'brand', maxShare: 0.4, window: 20, familiarOnly: true },
+});
+```
+
+- `feature` — schema key to cap (e.g. `'brand'`).
+- `maxShare` — max fraction of the recent window any one value may hold.
+- `window` — picks the share is measured over (default 20).
+- `familiarOnly` — when an over-cap winner can't be replaced by an under-cap
+  *familiar* item (one the user has positive signal for), keep it familiar
+  rather than inject an unfamiliar item. **Leave this on for taste-driven
+  feeds** — backfilling with any item instead drops feed familiarity sharply.
+
+`diagnostics.diversitySwapped` reports when a pick was a cap backfill.
+
 Advanced primitives (slot tables, interest state, bucket admission, the
-weighted sampler, and `seededRng` for deterministic tests) are exported from
-the same entry for callers building custom pipelines or CLIs on top.
+weighted sampler, the dual-bucket `bucketContribution`, and `seededRng` for
+deterministic tests) are exported from the same entry for callers building
+custom pipelines or CLIs on top.
 
 ## License
 

package/dist/reco.d.mts

@@ -39,7 +39,7 @@ interface SlotTableState {
 declare function emptyState(): SlotTableState;
 declare function observe(state: SlotTableState, value: string, weight: number, config?: SlotTableConfig): void;
 declare function decay(state: SlotTableState, factor: number): void;
-declare function contribution(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
+declare function contribution$1(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
 declare function isEmpty$1(state: SlotTableState): boolean;
 
 interface InterestConfig<T extends BaseItem> {
@@ -125,10 +125,12 @@ interface BucketConfig {
 declare function emptyBucket(): BucketState;
 declare function admit(state: BucketState, value: string, score: number, config?: BucketConfig): void;
 declare function powerOf(state: BucketState, value: string | null): number;
+declare function contribution(state: BucketState, value: string | null, epsilon: number): number;
 declare function isEmpty(state: BucketState): boolean;
 
 interface DualInterestConfig<T extends BaseItem> {
     schema: Schema<T>;
+    weightedScoring?: boolean;
 }
 interface DualBucketState {
     liked: Record<string, BucketState>;
@@ -156,16 +158,33 @@ declare function describe(state: DualBucketState, top?: number): {
     disliked: Record<string, [string, number][]>;
 };
 
+interface DiversityCap {
+    feature: string;
+    maxShare: number;
+    window?: number;
+    familiarOnly?: boolean;
+}
 interface DualRecommenderConfig<T extends BaseItem> {
     schema: Schema<T>;
     sampleSize?: number;
     shuffleThreshold?: number;
+    weightedScoring?: boolean;
+    seenWindow?: number;
+    diversityCap?: DiversityCap;
     rng?: RNG;
 }
+interface ResolvedDiversityCap {
+    feature: string;
+    maxShare: number;
+    window: number;
+    familiarOnly: boolean;
+}
 interface ResolvedConfig<T extends BaseItem> {
     interest: DualInterestConfig<T>;
     sampleSize: number;
     shuffleThreshold: number;
+    seenWindow: number;
+    diversityCap: ResolvedDiversityCap | null;
     rng: RNG;
 }
 interface DualRecommendDiagnostics<T extends BaseItem> {
@@ -176,6 +195,7 @@ interface DualRecommendDiagnostics<T extends BaseItem> {
     bestLiked: number;
     bestDisliked: number;
     freshPagesIssued: number;
+    diversitySwapped: boolean;
     breakdown: ItemScore['byFeature'] | null;
     runnersUp: Array<{
         item: T;
@@ -196,7 +216,10 @@ declare class DualBucketRecommender<T extends BaseItem> {
     readonly config: ResolvedConfig<T>;
     private ownedIds;
     private seen;
+    private seenOrder;
     private freshPagesIssued;
+    private recentValues;
+    private valueCounts;
     constructor(catalog: T[], config: DualRecommenderConfig<T>);
     setOwned(ids: Iterable<string>): void;
     setSampleSize(k: number): void;
@@ -204,6 +227,11 @@ declare class DualBucketRecommender<T extends BaseItem> {
     engage(item: T, score: number): void;
     recommend(count?: number): DualRecommendResult<T>;
     private pickOne;
+    private pickUnderCapReplacement;
+    private atCap;
+    private isFamiliar;
+    private markSeen;
+    private recordPick;
     private candidatePool;
     seenCount(): number;
     clearSeen(): void;
@@ -213,4 +241,4 @@ declare class DualBucketRecommender<T extends BaseItem> {
 declare function logDecadeBucket(value: number | null, multiplier?: number, prefix?: string): string | null;
 declare function yearBucket(year: number | null, bandSize?: number): string | null;
 
-export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };
+export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, type DiversityCap, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution as bucketContribution, contribution$1 as contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };

package/dist/reco.d.ts

@@ -39,7 +39,7 @@ interface SlotTableState {
 declare function emptyState(): SlotTableState;
 declare function observe(state: SlotTableState, value: string, weight: number, config?: SlotTableConfig): void;
 declare function decay(state: SlotTableState, factor: number): void;
-declare function contribution(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
+declare function contribution$1(state: SlotTableState, value: string | null, config?: SlotTableConfig): number;
 declare function isEmpty$1(state: SlotTableState): boolean;
 
 interface InterestConfig<T extends BaseItem> {
@@ -125,10 +125,12 @@ interface BucketConfig {
 declare function emptyBucket(): BucketState;
 declare function admit(state: BucketState, value: string, score: number, config?: BucketConfig): void;
 declare function powerOf(state: BucketState, value: string | null): number;
+declare function contribution(state: BucketState, value: string | null, epsilon: number): number;
 declare function isEmpty(state: BucketState): boolean;
 
 interface DualInterestConfig<T extends BaseItem> {
     schema: Schema<T>;
+    weightedScoring?: boolean;
 }
 interface DualBucketState {
     liked: Record<string, BucketState>;
@@ -156,16 +158,33 @@ declare function describe(state: DualBucketState, top?: number): {
     disliked: Record<string, [string, number][]>;
 };
 
+interface DiversityCap {
+    feature: string;
+    maxShare: number;
+    window?: number;
+    familiarOnly?: boolean;
+}
 interface DualRecommenderConfig<T extends BaseItem> {
     schema: Schema<T>;
     sampleSize?: number;
     shuffleThreshold?: number;
+    weightedScoring?: boolean;
+    seenWindow?: number;
+    diversityCap?: DiversityCap;
     rng?: RNG;
 }
+interface ResolvedDiversityCap {
+    feature: string;
+    maxShare: number;
+    window: number;
+    familiarOnly: boolean;
+}
 interface ResolvedConfig<T extends BaseItem> {
     interest: DualInterestConfig<T>;
     sampleSize: number;
     shuffleThreshold: number;
+    seenWindow: number;
+    diversityCap: ResolvedDiversityCap | null;
     rng: RNG;
 }
 interface DualRecommendDiagnostics<T extends BaseItem> {
@@ -176,6 +195,7 @@ interface DualRecommendDiagnostics<T extends BaseItem> {
     bestLiked: number;
     bestDisliked: number;
     freshPagesIssued: number;
+    diversitySwapped: boolean;
     breakdown: ItemScore['byFeature'] | null;
     runnersUp: Array<{
         item: T;
@@ -196,7 +216,10 @@ declare class DualBucketRecommender<T extends BaseItem> {
     readonly config: ResolvedConfig<T>;
     private ownedIds;
     private seen;
+    private seenOrder;
     private freshPagesIssued;
+    private recentValues;
+    private valueCounts;
     constructor(catalog: T[], config: DualRecommenderConfig<T>);
     setOwned(ids: Iterable<string>): void;
     setSampleSize(k: number): void;
@@ -204,6 +227,11 @@ declare class DualBucketRecommender<T extends BaseItem> {
     engage(item: T, score: number): void;
     recommend(count?: number): DualRecommendResult<T>;
     private pickOne;
+    private pickUnderCapReplacement;
+    private atCap;
+    private isFamiliar;
+    private markSeen;
+    private recordPick;
     private candidatePool;
     seenCount(): number;
     clearSeen(): void;
@@ -213,4 +241,4 @@ declare class DualBucketRecommender<T extends BaseItem> {
 declare function logDecadeBucket(value: number | null, multiplier?: number, prefix?: string): string | null;
 declare function yearBucket(year: number | null, bandSize?: number): string | null;
 
-export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };
+export { type BaseItem, type BucketConfig, type BucketState, DEFAULT_CAPACITY, DEFAULT_DECREMENT_CAP, DEFAULT_EPSILON, DEFAULT_INTEREST_CONFIG, DEFAULT_SLOT_CONFIG, type DiversityCap, DualBucketRecommender, type DualBucketState, type DualInterestConfig, type ItemScore as DualItemScore, type DualRecommendDiagnostics, type DualRecommendResult, type DualRecommenderConfig, type FeatureConfig, type InterestConfig, type InterestState, type RNG, type RecommendDiagnostics, type RecommendResult, Recommender, type RecommenderConfig, SIGNALS, type Schema, type SignalName, type Slot, type SlotTableConfig, type SlotTableState, admit, applyEvent, contribution as bucketContribution, contribution$1 as contribution, decay, defaultRng, describe$1 as describe, describe as describeDual, emptyBucket, emptyDualState, emptyInterest, emptyState, engageNegative, engagePositive, isCold$1 as isCold, isCold as isColdDual, isEmpty$1 as isEmpty, isEmpty as isEmptyBucket, logDecadeBucket, observe, powerOf, scoreItem$1 as scoreItem, scoreItem as scoreItemDual, seededRng, weightedSampleWithoutReplacement, yearBucket };

package/dist/reco.js

@@ -30,6 +30,7 @@ __export(reco_exports, {
   SIGNALS: () => SIGNALS,
   admit: () => admit,
   applyEvent: () => applyEvent,
+  bucketContribution: () => contribution2,
   contribution: () => contribution,
   decay: () => decay,
   defaultRng: () => defaultRng,
@@ -406,6 +407,14 @@ function powerOf(state, value) {
   const slot = state.slots.find((s) => s.value === value);
   return slot ? slot.power : 0;
 }
+function contribution2(state, value, epsilon) {
+  if (!value) return epsilon;
+  const slot = state.slots.find((s) => s.value === value);
+  if (!slot) return epsilon;
+  const total = state.slots.reduce((sum, s) => sum + s.power, 0);
+  if (total <= 0) return epsilon;
+  return epsilon + (1 - epsilon) * (slot.power / total);
+}
 function isEmpty2(state) {
   return state.slots.length === 0;
 }
@@ -445,14 +454,31 @@ function engageNegative(state, item, magnitude, config) {
   if (!Number.isFinite(magnitude) || magnitude <= 0) return;
   admitAcrossFeatures(state, "disliked", item, magnitude, config.schema);
 }
+function featureWeight2(fc, featureCount) {
+  if (typeof fc.weight === "number") return fc.weight;
+  return featureCount > 0 ? 1 / featureCount : 0;
+}
+function epsilonOf(fc) {
+  return fc.epsilon ?? DEFAULT_EPSILON;
+}
 function scoreItem2(state, item, config) {
   let liked = 0;
   let disliked = 0;
   const byFeature = [];
-  for (const [key, fc] of Object.entries(config.schema)) {
+  const entries = Object.entries(config.schema);
+  for (const [key, fc] of entries) {
     const value = fc.extract(item);
-    const l = powerOf(state.liked[key], value);
-    const d = powerOf(state.disliked[key], value);
+    let l;
+    let d;
+    if (config.weightedScoring) {
+      const w = featureWeight2(fc, entries.length);
+      const eps = epsilonOf(fc);
+      l = w * contribution2(state.liked[key], value, eps);
+      d = w * contribution2(state.disliked[key], value, eps);
+    } else {
+      l = powerOf(state.liked[key], value);
+      d = powerOf(state.disliked[key], value);
+    }
     liked += l;
     disliked += d;
     byFeature.push({ key, value, liked: l, disliked: d });
@@ -477,13 +503,21 @@ function describe2(state, top = 4) {
 }
 
 // src/reco/dual-bucket/recommender.ts
+var DEFAULT_DIVERSITY_WINDOW = 20;
 function resolve2(input) {
   return {
-    interest: { schema: input.schema },
+    interest: { schema: input.schema, weightedScoring: input.weightedScoring ?? false },
     // 100 is a heavy exploit setting; drop to 20–30 if exploration feels
     // weak. Live-tunable via setSampleSize().
     sampleSize: input.sampleSize ?? 100,
     shuffleThreshold: input.shuffleThreshold ?? 100,
+    seenWindow: input.seenWindow ?? 0,
+    diversityCap: input.diversityCap ? {
+      feature: input.diversityCap.feature,
+      maxShare: input.diversityCap.maxShare,
+      window: input.diversityCap.window ?? DEFAULT_DIVERSITY_WINDOW,
+      familiarOnly: input.diversityCap.familiarOnly ?? false
+    } : null,
     rng: input.rng ?? defaultRng
   };
 }
@@ -491,7 +525,12 @@ var DualBucketRecommender = class {
   constructor(catalog, config) {
     this.ownedIds = /* @__PURE__ */ new Set();
     this.seen = /* @__PURE__ */ new Set();
+    this.seenOrder = [];
     this.freshPagesIssued = 0;
+    // diversityCap bookkeeping: the capped-feature value of each recent pick,
+    // windowed, with a running count per value.
+    this.recentValues = [];
+    this.valueCounts = /* @__PURE__ */ new Map();
     this.catalog = catalog;
     this.byId = new Map(catalog.map((i) => [i.id, i]));
     this.config = resolve2(config);
@@ -523,7 +562,8 @@ var DualBucketRecommender = class {
       items.push(result.item);
       scores.push(result.diagnostics.bestNet);
       lastDiag = result.diagnostics;
-      this.seen.add(result.item.id);
+      this.markSeen(result.item.id);
+      this.recordPick(result.item);
     }
     return {
       items,
@@ -536,6 +576,7 @@ var DualBucketRecommender = class {
         bestLiked: 0,
         bestDisliked: 0,
         freshPagesIssued: this.freshPagesIssued,
+        diversitySwapped: false,
         breakdown: null,
         runnersUp: []
       }
@@ -545,6 +586,7 @@ var DualBucketRecommender = class {
     let pool = this.candidatePool();
     if (pool.length < this.config.shuffleThreshold) {
       this.seen.clear();
+      this.seenOrder.length = 0;
       this.freshPagesIssued += 1;
       pool = this.candidatePool();
     }
@@ -558,6 +600,19 @@ var DualBucketRecommender = class {
       const zero = scored.find((x) => x.s.net === 0);
       if (zero) winner = zero;
     }
+    let diversitySwapped = false;
+    const cap = this.config.diversityCap;
+    if (cap) {
+      const fc = this.config.interest.schema[cap.feature];
+      const winnerValue = fc ? fc.extract(winner.item) : null;
+      if (this.atCap(winnerValue)) {
+        const replacement = this.pickUnderCapReplacement(scored, winner.item.id, fc);
+        if (replacement && replacement.item.id !== winner.item.id) {
+          winner = replacement;
+          diversitySwapped = true;
+        }
+      }
+    }
     const runnersUp = scored.filter((x) => x.item.id !== winner.item.id).map((x) => ({
       item: x.item,
       net: x.s.net,
@@ -574,11 +629,71 @@ var DualBucketRecommender = class {
         bestLiked: winner.s.liked,
         bestDisliked: winner.s.disliked,
         freshPagesIssued: this.freshPagesIssued,
+        diversitySwapped,
         breakdown: winner.s.byFeature,
         runnersUp
       }
     };
   }
+  /** Choose a backfill when the top winner's value is over its diversity cap.
+   *  `scored` is sorted by net desc, so the first match is the best one. */
+  pickUnderCapReplacement(scored, winnerId, fc) {
+    const cap = this.config.diversityCap;
+    if (!cap || !fc) return null;
+    const valueOf = (x) => fc.extract(x.item);
+    const underCapFamiliar = scored.find(
+      (x) => x.item.id !== winnerId && !this.atCap(valueOf(x)) && this.isFamiliar(valueOf(x))
+    );
+    if (underCapFamiliar) return underCapFamiliar;
+    if (cap.familiarOnly) {
+      return scored.find((x) => x.item.id !== winnerId && this.isFamiliar(valueOf(x))) ?? null;
+    }
+    return scored.find((x) => x.item.id !== winnerId && !this.atCap(valueOf(x))) ?? null;
+  }
+  /** True when `value` already holds >= maxShare of the recent window. Not
+   *  enforced until the window has enough samples for a share to be
+   *  meaningful (otherwise the first pick is trivially "100%"). */
+  atCap(value) {
+    const cap = this.config.diversityCap;
+    if (!cap || value == null) return false;
+    const n = this.recentValues.length;
+    if (n < Math.ceil(1 / cap.maxShare)) return false;
+    return (this.valueCounts.get(value) ?? 0) / n >= cap.maxShare;
+  }
+  /** "User has positive signal for this capped-feature value." The exported
+   *  powerOf on the liked bucket is the whole familiarity test. */
+  isFamiliar(value) {
+    const cap = this.config.diversityCap;
+    if (!cap || value == null) return false;
+    const bucket = this.interest.liked[cap.feature];
+    return bucket ? powerOf(bucket, value) > 0 : false;
+  }
+  markSeen(id) {
+    if (this.seen.has(id)) return;
+    this.seen.add(id);
+    if (this.config.seenWindow <= 0) return;
+    this.seenOrder.push(id);
+    while (this.seenOrder.length > this.config.seenWindow) {
+      const evicted = this.seenOrder.shift();
+      if (evicted != null) this.seen.delete(evicted);
+    }
+  }
+  recordPick(item) {
+    const cap = this.config.diversityCap;
+    if (!cap) return;
+    const fc = this.config.interest.schema[cap.feature];
+    const value = fc ? fc.extract(item) : null;
+    if (value == null) return;
+    this.recentValues.push(value);
+    this.valueCounts.set(value, (this.valueCounts.get(value) ?? 0) + 1);
+    while (this.recentValues.length > cap.window) {
+      const old = this.recentValues.shift();
+      if (old == null) continue;
+      const c = (this.valueCounts.get(old) ?? 0) - 1;
+      if (c <= 0) this.valueCounts.delete(old);
+      else this.valueCounts.set(old, c);
+    }
+  }
   candidatePool() {
     return this.catalog.filter((i) => !this.ownedIds.has(i.id) && !this.seen.has(i.id));
   }
@@ -587,6 +702,9 @@ var DualBucketRecommender = class {
   }
   clearSeen() {
     this.seen.clear();
+    this.seenOrder.length = 0;
+    this.recentValues.length = 0;
+    this.valueCounts.clear();
     this.freshPagesIssued = 0;
   }
   reset() {
@@ -595,6 +713,9 @@ var DualBucketRecommender = class {
     this.interest.disliked = fresh.disliked;
     this.interest.totalEvents = 0;
     this.seen.clear();
+    this.seenOrder.length = 0;
+    this.recentValues.length = 0;
+    this.valueCounts.clear();
     this.freshPagesIssued = 0;
   }
 };
@@ -633,6 +754,7 @@ function yearBucket(year, bandSize = 5) {
   SIGNALS,
   admit,
   applyEvent,
+  bucketContribution,
   contribution,
   decay,
   defaultRng,

package/dist/reco.mjs

@@ -350,6 +350,14 @@ function powerOf(state, value) {
   const slot = state.slots.find((s) => s.value === value);
   return slot ? slot.power : 0;
 }
+function contribution2(state, value, epsilon) {
+  if (!value) return epsilon;
+  const slot = state.slots.find((s) => s.value === value);
+  if (!slot) return epsilon;
+  const total = state.slots.reduce((sum, s) => sum + s.power, 0);
+  if (total <= 0) return epsilon;
+  return epsilon + (1 - epsilon) * (slot.power / total);
+}
 function isEmpty2(state) {
   return state.slots.length === 0;
 }
@@ -389,14 +397,31 @@ function engageNegative(state, item, magnitude, config) {
   if (!Number.isFinite(magnitude) || magnitude <= 0) return;
   admitAcrossFeatures(state, "disliked", item, magnitude, config.schema);
 }
+function featureWeight2(fc, featureCount) {
+  if (typeof fc.weight === "number") return fc.weight;
+  return featureCount > 0 ? 1 / featureCount : 0;
+}
+function epsilonOf(fc) {
+  return fc.epsilon ?? DEFAULT_EPSILON;
+}
 function scoreItem2(state, item, config) {
   let liked = 0;
   let disliked = 0;
   const byFeature = [];
-  for (const [key, fc] of Object.entries(config.schema)) {
+  const entries = Object.entries(config.schema);
+  for (const [key, fc] of entries) {
     const value = fc.extract(item);
-    const l = powerOf(state.liked[key], value);
-    const d = powerOf(state.disliked[key], value);
+    let l;
+    let d;
+    if (config.weightedScoring) {
+      const w = featureWeight2(fc, entries.length);
+      const eps = epsilonOf(fc);
+      l = w * contribution2(state.liked[key], value, eps);
+      d = w * contribution2(state.disliked[key], value, eps);
+    } else {
+      l = powerOf(state.liked[key], value);
+      d = powerOf(state.disliked[key], value);
+    }
     liked += l;
     disliked += d;
     byFeature.push({ key, value, liked: l, disliked: d });
@@ -421,13 +446,21 @@ function describe2(state, top = 4) {
 }
 
 // src/reco/dual-bucket/recommender.ts
+var DEFAULT_DIVERSITY_WINDOW = 20;
 function resolve2(input) {
   return {
-    interest: { schema: input.schema },
+    interest: { schema: input.schema, weightedScoring: input.weightedScoring ?? false },
     // 100 is a heavy exploit setting; drop to 20–30 if exploration feels
     // weak. Live-tunable via setSampleSize().
     sampleSize: input.sampleSize ?? 100,
     shuffleThreshold: input.shuffleThreshold ?? 100,
+    seenWindow: input.seenWindow ?? 0,
+    diversityCap: input.diversityCap ? {
+      feature: input.diversityCap.feature,
+      maxShare: input.diversityCap.maxShare,
+      window: input.diversityCap.window ?? DEFAULT_DIVERSITY_WINDOW,
+      familiarOnly: input.diversityCap.familiarOnly ?? false
+    } : null,
     rng: input.rng ?? defaultRng
   };
 }
@@ -435,7 +468,12 @@ var DualBucketRecommender = class {
   constructor(catalog, config) {
     this.ownedIds = /* @__PURE__ */ new Set();
     this.seen = /* @__PURE__ */ new Set();
+    this.seenOrder = [];
     this.freshPagesIssued = 0;
+    // diversityCap bookkeeping: the capped-feature value of each recent pick,
+    // windowed, with a running count per value.
+    this.recentValues = [];
+    this.valueCounts = /* @__PURE__ */ new Map();
     this.catalog = catalog;
     this.byId = new Map(catalog.map((i) => [i.id, i]));
     this.config = resolve2(config);
@@ -467,7 +505,8 @@ var DualBucketRecommender = class {
       items.push(result.item);
       scores.push(result.diagnostics.bestNet);
       lastDiag = result.diagnostics;
-      this.seen.add(result.item.id);
+      this.markSeen(result.item.id);
+      this.recordPick(result.item);
     }
     return {
       items,
@@ -480,6 +519,7 @@ var DualBucketRecommender = class {
         bestLiked: 0,
         bestDisliked: 0,
         freshPagesIssued: this.freshPagesIssued,
+        diversitySwapped: false,
         breakdown: null,
         runnersUp: []
       }
@@ -489,6 +529,7 @@ var DualBucketRecommender = class {
     let pool = this.candidatePool();
     if (pool.length < this.config.shuffleThreshold) {
       this.seen.clear();
+      this.seenOrder.length = 0;
       this.freshPagesIssued += 1;
       pool = this.candidatePool();
     }
@@ -502,6 +543,19 @@ var DualBucketRecommender = class {
       const zero = scored.find((x) => x.s.net === 0);
       if (zero) winner = zero;
     }
+    let diversitySwapped = false;
+    const cap = this.config.diversityCap;
+    if (cap) {
+      const fc = this.config.interest.schema[cap.feature];
+      const winnerValue = fc ? fc.extract(winner.item) : null;
+      if (this.atCap(winnerValue)) {
+        const replacement = this.pickUnderCapReplacement(scored, winner.item.id, fc);
+        if (replacement && replacement.item.id !== winner.item.id) {
+          winner = replacement;
+          diversitySwapped = true;
+        }
+      }
+    }
     const runnersUp = scored.filter((x) => x.item.id !== winner.item.id).map((x) => ({
       item: x.item,
       net: x.s.net,
@@ -518,11 +572,71 @@ var DualBucketRecommender = class {
         bestLiked: winner.s.liked,
         bestDisliked: winner.s.disliked,
         freshPagesIssued: this.freshPagesIssued,
+        diversitySwapped,
         breakdown: winner.s.byFeature,
         runnersUp
       }
     };
   }
+  /** Choose a backfill when the top winner's value is over its diversity cap.
+   *  `scored` is sorted by net desc, so the first match is the best one. */
+  pickUnderCapReplacement(scored, winnerId, fc) {
+    const cap = this.config.diversityCap;
+    if (!cap || !fc) return null;
+    const valueOf = (x) => fc.extract(x.item);
+    const underCapFamiliar = scored.find(
+      (x) => x.item.id !== winnerId && !this.atCap(valueOf(x)) && this.isFamiliar(valueOf(x))
+    );
+    if (underCapFamiliar) return underCapFamiliar;
+    if (cap.familiarOnly) {
+      return scored.find((x) => x.item.id !== winnerId && this.isFamiliar(valueOf(x))) ?? null;
+    }
+    return scored.find((x) => x.item.id !== winnerId && !this.atCap(valueOf(x))) ?? null;
+  }
+  /** True when `value` already holds >= maxShare of the recent window. Not
+   *  enforced until the window has enough samples for a share to be
+   *  meaningful (otherwise the first pick is trivially "100%"). */
+  atCap(value) {
+    const cap = this.config.diversityCap;
+    if (!cap || value == null) return false;
+    const n = this.recentValues.length;
+    if (n < Math.ceil(1 / cap.maxShare)) return false;
+    return (this.valueCounts.get(value) ?? 0) / n >= cap.maxShare;
+  }
+  /** "User has positive signal for this capped-feature value." The exported
+   *  powerOf on the liked bucket is the whole familiarity test. */
+  isFamiliar(value) {
+    const cap = this.config.diversityCap;
+    if (!cap || value == null) return false;
+    const bucket = this.interest.liked[cap.feature];
+    return bucket ? powerOf(bucket, value) > 0 : false;
+  }
+  markSeen(id) {
+    if (this.seen.has(id)) return;
+    this.seen.add(id);
+    if (this.config.seenWindow <= 0) return;
+    this.seenOrder.push(id);
+    while (this.seenOrder.length > this.config.seenWindow) {
+      const evicted = this.seenOrder.shift();
+      if (evicted != null) this.seen.delete(evicted);
+    }
+  }
+  recordPick(item) {
+    const cap = this.config.diversityCap;
+    if (!cap) return;
+    const fc = this.config.interest.schema[cap.feature];
+    const value = fc ? fc.extract(item) : null;
+    if (value == null) return;
+    this.recentValues.push(value);
+    this.valueCounts.set(value, (this.valueCounts.get(value) ?? 0) + 1);
+    while (this.recentValues.length > cap.window) {
+      const old = this.recentValues.shift();
+      if (old == null) continue;
+      const c = (this.valueCounts.get(old) ?? 0) - 1;
+      if (c <= 0) this.valueCounts.delete(old);
+      else this.valueCounts.set(old, c);
+    }
+  }
   candidatePool() {
     return this.catalog.filter((i) => !this.ownedIds.has(i.id) && !this.seen.has(i.id));
   }
@@ -531,6 +645,9 @@ var DualBucketRecommender = class {
   }
   clearSeen() {
     this.seen.clear();
+    this.seenOrder.length = 0;
+    this.recentValues.length = 0;
+    this.valueCounts.clear();
     this.freshPagesIssued = 0;
   }
   reset() {
@@ -539,6 +656,9 @@ var DualBucketRecommender = class {
     this.interest.disliked = fresh.disliked;
     this.interest.totalEvents = 0;
     this.seen.clear();
+    this.seenOrder.length = 0;
+    this.recentValues.length = 0;
+    this.valueCounts.clear();
     this.freshPagesIssued = 0;
   }
 };
@@ -576,6 +696,7 @@ export {
   SIGNALS,
   admit,
   applyEvent,
+  contribution2 as bucketContribution,
   contribution,
   decay,
   defaultRng,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logg/signals",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Universal event tracking SDK for Logg Signals, with an embeddable on-device recommender",
   "main": "dist/index.js",
   "module": "dist/index.mjs",