@woosh/meep-engine 2.165.6 → 2.166.0

package/src/core/cache/wtinylfu/CacheWTinylfu.js

@@ -0,0 +1,807 @@
+/**
+ * Frequency-based admission cache, using W-TinyLFU (Window Tiny Least Frequency)
+ *
+ * Cache regions:
+ * 1. Window (LRU)          Burst traffic
+ * 2. Main (SLRU)           Long-term residency
+ *      Probation (LRU)     Trial area for candidate from Window or demoted from Protected
+ *      Protected (LRU)     VIP area for frequently accessed items
+ *
+ * Life cycle:
+ * 1. Admission: New items enter the Window.
+ * 2. Promoting to Probation: If Window is full, the Candidate (oldest window element) attempts to move
+ *    into the Probation.
+ * 3. Frequency Duel: If the Probation is full, the Candidate (oldest window element) competes against the
+ *    Victim (oldest probation element) using a Count-Min Sketch frequency filter.
+ * 4. Promotion to Protected: A Probation item accessed again (or exceeds a threshold) is promoted to the
+ *    Protected list.
+ * 5. Demotion: If the Protected list reaches its capacity, the oldest item is demoted
+ *    to the Probation list to make room.
+ *
+ * Capacity management:
+ * Can be governed by count or weight
+ * Window       ~1%
+ * Probation    ~20%
+ * Protected    ~80%
+ * The Main cache segments are dynamic. Protected is capped at ~80%. Probation will vary
+ * as it consumes the remainder, based on promotion/demotion influence.
+ */
+
+import {CacheRegionWTinylfu} from "./CacheRegionWTinylfu.js";
+import {assert} from "../../assert.js";
+import {CacheElementWTinylfu} from "./CacheElementWTinylfu.js";
+import {CacheRegionType} from "./CacheRegionType.js";
+import {returnZero} from "../../function/returnZero.js";
+import {returnOne} from "../../function/returnOne.js";
+import {FrequencySketch} from "../FrequencySketch.js";
+import {invokeObjectHash} from "../../model/object/invokeObjectHash.js";
+import {invokeObjectEquals} from "../../model/object/invokeObjectEquals.js";
+import {HashMap} from "../../collection/map/HashMap.js";
+import {mainCapacity, exceedsMainWeight, cannotFitMain, winsAdmissionDuel, shouldPromoteToProtected, classifyAdmission, AdmissionRoute} from "./wtinylfuDecisions.js";
+import {Signal} from "../../events/signal/Signal.js";
+
+/**
+ * Cap on the reuse pool of evicted element objects. Under churn the pool hovers near 1 (one evict per
+ * insert), so this only bounds it under remove-heavy bursts; past the cap, elements are left to GC.
+ * @type {number}
+ */
+const ELEMENT_POOL_MAX = 256;
+
+export class CacheWTinylfu {
+
+    /**
+     * @type {number}
+     * @private
+     */
+    #maxWeight = Number.POSITIVE_INFINITY;
+
+    /**
+     * @type {number}
+     * @private
+     */
+    #promotionThreshold = 1;
+
+    /**
+     * @type {function(Key):number}
+     * @private
+     */
+    #keyHashFunction = invokeObjectHash;
+
+    /**
+     * Cache regions — kept as three direct fields (not a {window,trial,protected} record) so each hot-path
+     * access is a single property read rather than two.
+     * @type {CacheRegionWTinylfu}
+     * @private
+     */
+    #window;
+    /** @type {CacheRegionWTinylfu} @private */
+    #trial;
+    /** @type {CacheRegionWTinylfu} @private */
+    #protected;
+
+    /**
+     *
+     * @type {FrequencySketch}
+     * @private
+     */
+    #sketch = new FrequencySketch();
+
+    /**
+     * @type {function(Key): number}
+     * @private
+     */
+    #keyWeigher;
+
+    /**
+     * @type {function(Value): number}
+     * @private
+     */
+    #valueWeigher;
+
+    /**
+     * @type {HashMap<Key, CacheElementWTinylfu<Key,Value>>}
+     * @private
+     */
+    #data;
+
+    /**
+     * Reuse pool of evicted element objects. `put` takes one from here instead of allocating a fresh
+     * element; under churn this makes steady-state inserts allocation-free. Capped at {@link ELEMENT_POOL_MAX}.
+     * @type {CacheElementWTinylfu[]}
+     * @private
+     */
+    #elementPool = [];
+
+    /**
+     * Dispatched when an element is added or its value replaced. send2(key, value)
+     * @type {Signal}
+     */
+    onSet = new Signal();
+
+    /**
+     * Dispatched when an element leaves the cache, by eviction or explicit remove. send2(key, value)
+     * @type {Signal}
+     */
+    onRemoved = new Signal();
+
+    /**
+     * Dispatched when an element leaves due to capacity, immediately after onRemoved. send2(key, value)
+     * @type {Signal}
+     */
+    onEvicted = new Signal();
+
+    /**
+     * Dispatched when admission control turns an element away (reject-guard or lost duel) — it was
+     * never stored. Unique to W-TinyLFU. send2(key, value)
+     * @type {Signal}
+     */
+    onRejected = new Signal();
+
+    /**
+     *
+     * @param {number} [maxWeight=Number.POSITIVE_INFINITY] total weight budget of the cache; an element's weight is keyWeigher(key) + valueWeigher(value)
+     * @param {number} [promotionThreshold=1] frequency an item must exceed to be promoted out of Trial (Probation)
+     * @param {number} [capacityWindow=1] weight cap of the Window region (burst buffer)
+     * @param {number} [capacityProtected=1] weight cap of the Protected region (VIP segment of Main)
+     * @param {function(key:Key):number} [keyWeigher= key=>0] function to compute weight of a key
+     * @param {function(value:Value):number} [valueWeigher= value=>1] function to compute weight of a value
+     * @param {function(Key):number} [keyHashFunction]
+     * @param {function(Key, Key):boolean} [keyEqualityFunction]
+     */
+    constructor({
+                    maxWeight = Number.POSITIVE_INFINITY,
+                    promotionThreshold = 1,
+                    capacityWindow = 1,
+                    capacityProtected = 1,
+                    keyWeigher = returnZero,
+                    valueWeigher = returnOne,
+                    keyHashFunction = invokeObjectHash,
+                    keyEqualityFunction = invokeObjectEquals
+                } = {}) {
+
+        /**
+         * @param {number} parameter
+         * @param {string} message
+         */
+        const numberAssert = (parameter, message) => {
+            assert.isNumber(parameter, message);
+            assert.notNaN(parameter, message);
+            assert.greaterThanOrEqual(parameter, 0, message +' < 0');
+        }
+
+        numberAssert(maxWeight, 'maxWeight');
+        numberAssert(promotionThreshold, 'promotionThreshold');
+        numberAssert(capacityWindow, 'capacityWindow');
+        numberAssert(capacityProtected, 'capacityProtected');
+
+        const trialRegionSize = maxWeight - (capacityWindow + capacityProtected)
+        assert.greaterThan(trialRegionSize, 0, "probation region <= 0");
+        assert.greaterThanOrEqual(trialRegionSize, capacityWindow, 'capacityWindow > trialRegionSize');
+
+        assert.isFunction(keyWeigher, 'keyWeigher');
+        assert.isFunction(valueWeigher, 'valueWeigher');
+        assert.isFunction(keyHashFunction, 'keyHashFunction');
+        assert.isFunction(keyEqualityFunction, 'keyEqualityFunction');
+
+
+        this.#maxWeight = maxWeight;
+        this.#promotionThreshold = promotionThreshold;
+        this.#keyHashFunction = keyHashFunction;
+
+        this.#window = new CacheRegionWTinylfu({maxWeight: capacityWindow});
+        this.#trial = new CacheRegionWTinylfu({});
+        this.#protected = new CacheRegionWTinylfu({maxWeight: capacityProtected});
+
+        this.#keyWeigher = keyWeigher;
+        this.#valueWeigher = valueWeigher;
+
+        this.#data = new HashMap({
+            keyHashFunction,
+            keyEqualityFunction
+        });
+
+        // The sketch is sized dynamically to the live element count in __admit; seed a minimal table.
+        this.#sketch.ensureCapacity(0);
+    }
+
+    /**
+     * Update the recency & frequency of the cache element
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    __touch(element) {
+        this.__incrementSketch(element);
+        this.__onAccess(element);
+    }
+
+    /**
+     * Recency + promotion side of an access (no frequency increment).
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    __onAccess(element) {
+        switch (element.region) {
+            case CacheRegionType.Window:
+                this.#window.touch(element);
+                break;
+            case CacheRegionType.Trial:
+                this.__onTrialAccess(element)
+                break;
+            case CacheRegionType.Protected:
+                this.#protected.touch(element);
+                break;
+            default:
+                throw new Error ("Invalid region found");
+        }
+    }
+    /**
+     * Access of a Trial element: promote to Protected if hot enough and it fits, else bump recency.
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    __onTrialAccess(element) {
+        const trialRegion = this.#trial;
+        const protectedRegion = this.#protected;
+
+        if (this.__shouldPromoteToProtected(element)) {
+            trialRegion.remove(element);
+
+            element.region = CacheRegionType.Protected;
+            protectedRegion.add(element);
+
+            while (protectedRegion.wouldExceedCapacity())
+            {
+                const demoted = protectedRegion.findEvictionVictim();
+                protectedRegion.remove(demoted);
+
+                demoted.region = CacheRegionType.Trial;
+                trialRegion.add(demoted);
+            }
+        }
+        else {
+            trialRegion.touch(element);
+        }
+    }
+
+    /**
+     * Record an access to `element` in the frequency sketch (using its cached key hash).
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    __incrementSketch(element) {
+        this.#sketch.increment(element.keyHash);
+    }
+
+    /**
+     * Estimated access frequency of `element` from the sketch (using its cached key hash).
+     * @param {CacheElementWTinylfu} element
+     * @returns {number}
+     * @private
+     */
+    __frequency(element) {
+        return this.#sketch.frequency(element.keyHash);
+    }
+
+    /**
+     * Is `element` hot enough and small enough to be promoted from Trial to Protected?
+     * (frequency above threshold AND fits Protected — contract in {@link shouldPromoteToProtected})
+     * @param {CacheElementWTinylfu} element
+     * @returns {boolean}
+     * @private
+     */
+    __shouldPromoteToProtected(element) {
+        return shouldPromoteToProtected(this.__frequency(element), this.#promotionThreshold, element.weight, this.#protected.maxWeight);
+    }
+
+    /**
+     * The admission duel: does the candidate beat the victim on frequency?
+     * (contract in {@link winsAdmissionDuel})
+     * @param {CacheElementWTinylfu} candidate
+     * @param {CacheElementWTinylfu} victim
+     * @returns {boolean}
+     * @private
+     */
+    __admissionDuel(candidate, victim) {
+        return winsAdmissionDuel(this.__frequency(candidate), this.__frequency(victim));
+    }
+
+    /**
+     * Explicitly remove (invalidate) a key. Fires onRemoved, but not onEvicted (not capacity-driven).
+     * @param {Key} key
+     * @returns {boolean} true if the key was present and removed
+     */
+    remove(key) {
+        const element = this.#data.get(key);
+        if (element === undefined) {
+            return false;
+        }
+
+        this.__evict(element, element.weight, false);   // manual removal: onRemoved only, not onEvicted
+        return true;
+    }
+
+    /**
+     * Remove all entries. Fires onRemoved for each (explicit removal, so not onEvicted).
+     * The frequency sketch is left intact (history decays on its own).
+     */
+    clear() {
+        for (const element of this.#data.values()) {
+            this.onRemoved.send2(element.key, element.value);
+        }
+
+        this.#data.clear();
+        this.#window.clear();
+        this.#trial.clear();
+        this.#protected.clear();
+    }
+
+    /**
+     * An element's weight: keyWeigher(key) + valueWeigher(value). Asserts each is a non-negative number.
+     * @param {Key} key
+     * @param {Value} value
+     * @returns {number}
+     * @private
+     */
+    __computeElementWeight(key, value) {
+        const keyWeight = this.#keyWeigher(key);
+
+        assert.greaterThanOrEqual(keyWeight, 0, 'keyWeight');
+
+        const valueWeight = this.#valueWeigher(value);
+
+        assert.greaterThanOrEqual(valueWeight, 0, 'valueWeight');
+
+        return keyWeight + valueWeight;
+    }
+
+    /**
+     * Total weight Main (Trial + Protected) is allowed to hold.
+     * @returns {number}
+     * @private
+     */
+    __mainCapacity() {
+        return mainCapacity(this.#maxWeight, this.#window.maxWeight);
+    }
+
+    /**
+     * Would Main exceed its budget once `extraWeight` is added, counting current occupancy?
+     * (contract in {@link exceedsMainWeight})
+     * @param {number} [extraWeight=0]
+     * @returns {boolean}
+     * @private
+     */
+    __exceedsMainWeight(extraWeight = 0) {
+        return exceedsMainWeight(this.#trial.weight, this.#protected.weight, extraWeight, this.__mainCapacity());
+    }
+
+    /**
+     * Could `weight` never fit Main, even with Trial fully evicted? (Protected's live weight is the
+     * immovable floor — contract in {@link cannotFitMain}.)
+     * @param {number} weight
+     * @returns {boolean}
+     * @private
+     */
+    __cannotFitMain(weight) {
+        return cannotFitMain(this.#protected.weight, weight, this.__mainCapacity());
+    }
+
+    /**
+     * Decide where an element of `weight` is routed on admission: Reject, Window, or Trial.
+     * (contract in {@link classifyAdmission})
+     * @param {number} weight
+     * @returns {number} one of AdmissionRoute
+     * @private
+     */
+    __classifyAdmission(weight) {
+        return classifyAdmission(weight, this.#protected.weight, this.#window.maxWeight, this.__mainCapacity());
+    }
+
+    /**
+     * Demote a Protected element to Trial. Pure relocation — the caller restores Main's budget.
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    __demoteToTrial(element) {
+        this.#protected.remove(element);
+        element.region = CacheRegionType.Trial;
+        this.#trial.add(element);
+    }
+
+    /**
+     * Refit a grown Protected element
+     * @param {CacheElementWTinylfu} element
+     * @param {number} newWeight
+     * @param {number} delta
+     * @returns {boolean} whether `element` survived
+     * @private
+     */
+    __refitGrownProtected(element, newWeight, delta) {
+        // Too big to ever fit Main, even alone → cannot keep it.
+        if (newWeight > this.__mainCapacity()) {
+            this.__evict(element);
+            return false;
+        }
+
+        element.weight = newWeight;
+        this.#protected.adjustWeight(delta);
+        this.#protected.touch(element);   // keep the updated element (protect from demotion below)
+
+        while (this.#protected.wouldExceedCapacity()) {
+            this.__demoteToTrial(this.#protected.findEvictionVictim());
+        }
+        while (this.__exceedsMainWeight()) {
+            this.__evict(this.__trialEvictionVictim());
+        }
+
+        return true;
+    }
+
+    /**
+     * Refit a grown Trial element
+     * @param {CacheElementWTinylfu} element
+     * @param {number} newWeight
+     * @param {number} delta
+     * @returns {boolean} whether `element` survived
+     * @private
+     */
+    __refitGrownTrial(element, newWeight, delta) {
+        if (this.__cannotFitMain(newWeight)) {
+            this.__evict(element);
+            return false;
+        }
+
+        element.weight = newWeight;
+        this.#trial.adjustWeight(delta);
+        this.#trial.touch(element);   // keep the updated element (protect from eviction below)
+
+        while (this.__exceedsMainWeight()) {
+            this.__evict(this.__trialEvictionVictim());
+        }
+
+        return true;
+    }
+
+    /**
+     * Refit a grown Window element
+     * @param {CacheElementWTinylfu} element
+     * @param {number} newWeight
+     * @param {number} delta
+     * @returns {boolean} whether `element` survived
+     * @private
+     */
+    __refitGrownWindow(element, newWeight, delta) {
+        const oldWeight = element.weight;
+
+        // Same placement decision as admission: the grown element either no longer fits Main (evict),
+        // outgrew Window (→ Trial), or still fits Window.
+        const route = this.__classifyAdmission(newWeight);
+
+        switch (route) {
+            case AdmissionRoute.REJECT:
+                this.__evict(element);   // at oldWeight — weight not yet changed
+                return false;
+            case AdmissionRoute.TRIAL:
+                element.weight = newWeight;
+                return this.__nominateWindowToTrial(element, oldWeight);
+            case AdmissionRoute.WINDOW:
+                // keep it (MRU) and nominate older Window residents to Trial to absorb the growth
+                element.weight = newWeight;
+                this.#window.adjustWeight(delta);
+                this.#window.touch(element);
+                while (this.#window.wouldExceedCapacity()) {
+                    this.__nominateWindowToTrial(this.#window.findEvictionVictim());
+                }
+                return true;
+        }
+    }
+
+    /**
+     * Route an update to an existing key: shrink/same-weight applies in place, a growth dispatches to the
+     * region's refit handler. On survival, commits the new value and counts the access.
+     * @param {CacheElementWTinylfu} element
+     * @param {Value} newValue
+     * @private
+     */
+    __routeUpdate(element, newValue) {
+        const newWeight = this.__computeElementWeight(element.key, newValue);
+        const delta = newWeight - element.weight;
+
+        // An update is an access — count its frequency up front, so it weighs into any
+        // admission duel the refit triggers.
+        this.__incrementSketch(element);
+
+        let survived;
+        if (delta <= 0) {
+            element.weight = newWeight;
+            this.__regionOf(element).adjustWeight(delta);
+            survived = true;
+        } else {
+            switch (element.region) {
+                case CacheRegionType.Window:
+                    survived = this.__refitGrownWindow(element, newWeight, delta);
+                    break;
+                case CacheRegionType.Trial:
+                    survived = this.__refitGrownTrial(element, newWeight, delta);
+                    break;
+                case CacheRegionType.Protected:
+                    survived = this.__refitGrownProtected(element, newWeight, delta);
+                    break;
+                default:
+                    throw new Error("Invalid region found");
+            }
+        }
+
+        if (survived) {
+            element.value = newValue;   // commit payload after the element's place is secured
+            this.__onAccess(element);   // recency + promotion (frequency already counted above)
+            this.onSet.send2(element.key, newValue);   // value replaced
+        }
+    }
+
+    /**
+     * Relocate a resident into Trial (already removed from its prior region by the caller).
+     * @param {CacheElementWTinylfu} movedElement
+     * @private
+     */
+    __moveToTrial(movedElement) {
+        movedElement.region = CacheRegionType.Trial;
+        this.#trial.add(movedElement);
+    }
+
+    /**
+     * First-time admission: place a new element in `region`, register it in the lookup map,
+     * and record its frequency.
+     * @param {CacheElementWTinylfu} element
+     * @param {CacheRegionType} region
+     * @private
+     */
+    __admit(element, region) {
+        element.region = region;
+        this.__regionOf(element).add(element);
+        this.#data.set(element.key, element);
+        this.#sketch.ensureCapacity(this.#data.size);   // grow the sketch to track the live working set
+        this.__incrementSketch(element);
+
+        this.onSet.send2(element.key, element.value);
+    }
+
+    /**
+     * Remove an element from its region's list and the lookup map. Always fires onRemoved; also fires
+     * onEvicted when capacity-driven (`evicted`, the default), but not for manual removal.
+     * @param {CacheElementWTinylfu} element
+     * @param {number} [weight=element.weight]
+     * @param {boolean} [evicted=true] true for capacity eviction, false for explicit removal
+     * @private
+     */
+    __evict(element, weight = element.weight, evicted = true) {
+        this.__regionOf(element).remove(element, weight);
+        this.#data.delete(element.key);
+
+        this.onRemoved.send2(element.key, element.value);
+        if (evicted) {
+            this.onEvicted.send2(element.key, element.value);
+        }
+        this.#releaseElement(element);   // fully detached now — return it to the reuse pool
+    }
+
+    /**
+     * Return a fully-detached element to the reuse pool, clearing its references so it pins no user data.
+     * Caller MUST have already removed it from its region list and the lookup map, and fired any signals
+     * (which read key/value) — this nulls those out.
+     * @param {CacheElementWTinylfu} element
+     * @private
+     */
+    #releaseElement(element) {
+        element.key = null;
+        element.value = null;
+        element.next = null;
+        element.previous = null;
+
+        if (this.#elementPool.length < ELEMENT_POOL_MAX) {
+            this.#elementPool.push(element);
+        }
+    }
+
+    /**
+     * @param {CacheElementWTinylfu} element
+     * @returns {CacheRegionWTinylfu}
+     * @private
+     */
+    __regionOf(element) {
+        switch (element.region) {
+            case CacheRegionType.Window:    return this.#window;
+            case CacheRegionType.Trial:     return this.#trial;
+            case CacheRegionType.Protected: return this.#protected;
+            default: throw new Error("Invalid region found");
+        }
+    }
+
+    /**
+     * Earn `element` a place in Trial: if Main is over budget, duel it against the Trial LRU victim and,
+     * on a win, evict Trial victims until it fits. Verdict only — the caller owns the element's data entry.
+     * @param {CacheElementWTinylfu} element
+     * @returns {boolean} true if `element` is admitted and space was made for it;
+     *  false if it lost the admission duel.
+     * @private
+     */
+    __prepareTrialSpaceFor(element) {
+        if (!this.__exceedsMainWeight(element.weight)) {
+            return true;
+        }
+
+        if (!this.__admissionDuel(element, this.__trialEvictionVictim())) {
+            return false;
+        }
+
+        // by design: the candidate duels only the Trial LRU victim; a win may then cascade several
+        // evictions when weighted (the candidate proved it beats the coldest resident — we commit).
+        while (this.__exceedsMainWeight(element.weight)) {
+            this.__evict(this.__trialEvictionVictim());
+        }
+
+        return true;
+    }
+
+    /**
+     * @returns {CacheElementWTinylfu} Trial's LRU eviction victim
+     * @throws
+     * if Trial is empty while Main is over capacity (invariant: callers guarantee Trial holds enough evictable weight)
+     * @private
+     */
+    __trialEvictionVictim() {
+        const victim = this.#trial.findEvictionVictim();
+        if (!victim) {
+            throw new Error("Cache violation: no evictable victim in Trial while over capacity");
+        }
+        return victim;
+    }
+
+    /**
+     * Move a Window resident toward Trial through the admission duel; on a loss it is evicted
+     * (onRemoved + onEvicted).
+     * @param {CacheElementWTinylfu} candidate
+     * @param {number} [weight=candidate.weight] weight to reclaim from Window (override when it has changed)
+     * @returns {boolean} whether the candidate survived into Trial
+     * @private
+     */
+    __nominateWindowToTrial(candidate, weight = candidate.weight) {
+        this.#window.remove(candidate, weight);
+
+        if (this.__prepareTrialSpaceFor(candidate)) {
+            this.__moveToTrial(candidate);
+            return true;
+        } else {
+            // lost the duel — a resident is evicted
+            this.#data.delete(candidate.key);
+            this.onRemoved.send2(candidate.key, candidate.value);
+            this.onEvicted.send2(candidate.key, candidate.value);
+            this.#releaseElement(candidate);
+            return false;
+        }
+    }
+
+    /**
+     * Evict Window's LRU residents (nominating each to Trial) until `incomingWeight` fits.
+     * @param {number} incomingWeight
+     * @private
+     */
+    __makeRoomInWindow(incomingWeight) {
+        while (this.#window.wouldExceedCapacity(incomingWeight)) {
+            const victim = this.#window.findEvictionVictim();
+            if (!victim) {
+                // invariant: over capacity implies at least one resident
+                throw new Error("Cache violation: no evictable victim in Window while over capacity");
+            }
+            this.__nominateWindowToTrial(victim);
+        }
+    }
+
+    /**
+     * Admit a new element that is too big for Window straight into the Trial duel; on a loss it is
+     * rejected (onRejected) — it was never stored.
+     * @param {CacheElementWTinylfu} newElement
+     * @private
+     */
+    __nominateDirectToTrial(newElement) {
+        if (this.__prepareTrialSpaceFor(newElement)) {
+            this.__admit(newElement, CacheRegionType.Trial);
+        } else {
+            // lost the duel — newcomer never admitted
+            this.onRejected.send2(newElement.key, newElement.value);
+            this.#releaseElement(newElement);
+        }
+    }
+
+    /**
+     * Route a brand-new element per classifyAdmission: reject outright, insert into Window, or send it to
+     * the Trial duel.
+     * @param {CacheElementWTinylfu} newElement
+     * @private
+     */
+    __routeAdmission(newElement) {
+        const weight = newElement.weight;
+
+        // Decision: where does this element go? (see classifyAdmission — TRIAL is a lower bar than
+        // Protected; an element too big for Protected is still a valid, pinned Trial resident.)
+        const route = this.__classifyAdmission(weight);
+
+        switch (route) {
+            case AdmissionRoute.REJECT:
+                this.onRejected.send2(newElement.key, newElement.value);   // could never fit Main
+                return;
+            case AdmissionRoute.TRIAL:
+                this.__nominateDirectToTrial(newElement);
+                break;
+            case AdmissionRoute.WINDOW:
+                this.__makeRoomInWindow(weight);
+                this.__admit(newElement, CacheRegionType.Window);
+                break;
+        }
+    }
+
+    /**
+     * Insert a new entry, or update the value of an existing key. The main write entry point.
+     * @param {Key} key
+     * @param {Value} value
+     */
+    put(key, value){
+        let element = this.#data.get(key);
+
+        if (element !== undefined) {
+            this.__routeUpdate(element, value);
+            return;
+        }
+
+        // Reuse an evicted element if one is pooled, else allocate. Both arrive with next/previous null.
+        const pool = this.#elementPool;
+        element = pool.length > 0 ? pool.pop() : new CacheElementWTinylfu();
+        element.key = key;
+        element.keyHash = this.#keyHashFunction(key) | 0;   // hash once; `| 0` keeps it an inline SMI (no boxing)
+        element.value = value;
+        element.region = CacheRegionType.Window;
+        element.weight = this.__computeElementWeight(key, value);
+
+        this.__routeAdmission(element);
+    }
+
+    /**
+     * Look up a key. A hit counts as an access (recency + frequency, and may trigger promotion).
+     * @param {Key} key
+     * @returns {Value|null} the cached value, or null if not found
+     */
+    get(key) {
+        const element = this.#data.get(key);
+
+        if (element === undefined) {
+            return null;
+        }
+
+        this.__touch(element);   // a read is an access: frequency + recency + promotion
+        return element.value;
+    }
+
+    // ── diagnostics (inspection only; not part of the cache contract) ──
+
+    /**
+     * @internal Diagnostic for tests/monitoring: which region currently holds `key`, or null if absent.
+     * Returns the immutable {@link CacheRegionType} — it does NOT expose the element itself.
+     * @param {Key} key
+     * @returns {CacheRegionType|null}
+     */
+    inspectRegion(key) {
+        const element = this.#data.get(key);
+        return element === undefined ? null : element.region;
+    }
+
+    /**
+     * @internal Diagnostic for tests/monitoring: the live weight currently held by each region.
+     * @returns {{window: number, trial: number, protected: number}}
+     */
+    inspectWeights() {
+        return {
+            window: this.#window.weight,
+            trial: this.#trial.weight,
+            protected: this.#protected.weight,
+        };
+    }
+}