@logg/signals 0.4.0 → 0.5.0

package/README.md

@@ -542,6 +542,47 @@ 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, the dual-bucket `bucketContribution`, and `seededRng` for
 deterministic tests) are exported from the same entry for callers building

package/dist/reco.d.mts

@@ -158,17 +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> {
@@ -179,6 +195,7 @@ interface DualRecommendDiagnostics<T extends BaseItem> {
     bestLiked: number;
     bestDisliked: number;
     freshPagesIssued: number;
+    diversitySwapped: boolean;
     breakdown: ItemScore['byFeature'] | null;
     runnersUp: Array<{
         item: T;
@@ -199,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;
@@ -207,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;
@@ -216,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 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 };
+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

@@ -158,17 +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> {
@@ -179,6 +195,7 @@ interface DualRecommendDiagnostics<T extends BaseItem> {
     bestLiked: number;
     bestDisliked: number;
     freshPagesIssued: number;
+    diversitySwapped: boolean;
     breakdown: ItemScore['byFeature'] | null;
     runnersUp: Array<{
         item: T;
@@ -199,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;
@@ -207,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;
@@ -216,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 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 };
+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

@@ -503,6 +503,7 @@ function describe2(state, top = 4) {
 }
 
 // src/reco/dual-bucket/recommender.ts
+var DEFAULT_DIVERSITY_WINDOW = 20;
 function resolve2(input) {
   return {
     interest: { schema: input.schema, weightedScoring: input.weightedScoring ?? false },
@@ -510,6 +511,13 @@ function resolve2(input) {
     // 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
   };
 }
@@ -517,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);
@@ -549,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,
@@ -562,6 +576,7 @@ var DualBucketRecommender = class {
         bestLiked: 0,
         bestDisliked: 0,
         freshPagesIssued: this.freshPagesIssued,
+        diversitySwapped: false,
         breakdown: null,
         runnersUp: []
       }
@@ -571,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();
     }
@@ -584,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,
@@ -600,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));
   }
@@ -613,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() {
@@ -621,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;
   }
 };

package/dist/reco.mjs

@@ -446,6 +446,7 @@ function describe2(state, top = 4) {
 }
 
 // src/reco/dual-bucket/recommender.ts
+var DEFAULT_DIVERSITY_WINDOW = 20;
 function resolve2(input) {
   return {
     interest: { schema: input.schema, weightedScoring: input.weightedScoring ?? false },
@@ -453,6 +454,13 @@ function resolve2(input) {
     // 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
   };
 }
@@ -460,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);
@@ -492,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,
@@ -505,6 +519,7 @@ var DualBucketRecommender = class {
         bestLiked: 0,
         bestDisliked: 0,
         freshPagesIssued: this.freshPagesIssued,
+        diversitySwapped: false,
         breakdown: null,
         runnersUp: []
       }
@@ -514,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();
     }
@@ -527,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,
@@ -543,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));
   }
@@ -556,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() {
@@ -564,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;
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logg/signals",
-  "version": "0.4.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",