@beingmartinbmc/ojas 0.2.0

package/dist/aahar/index.js

@@ -0,0 +1,657 @@
+"use strict";
+/**
+ * Ojas Aahar (ओजस आहार) — AI Cognitive Nutrition System
+ *
+ * Governs what an AI agent cognitively consumes.
+ * Maintains context quality, cognitive load regulation,
+ * and runtime attention optimization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Aahar = void 0;
+const types_1 = require("../types");
+const scoring_1 = require("./scoring");
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function now() {
+    return new Date().toISOString();
+}
+function healthScore(value, source) {
+    return { value: clamp(value), timestamp: now(), source };
+}
+function clamp(v, min = 0, max = 1) {
+    return Math.max(min, Math.min(max, v));
+}
+// ─── Aahar Engine ────────────────────────────────────────────────────────────
+class Aahar {
+    policy;
+    history = [];
+    /**
+     * Per-source retrieval tally. Driven by `recordRetrieval(itemId)` —
+     * when the agent re-fetches an item that Aahar previously rejected,
+     * the source's count rises. The next call to `filter()` softens the
+     * relevance threshold for that source so we stop rejecting items
+     * the agent keeps asking for. Self-tunes from observed retrieval
+     * pressure.
+     */
+    retrievalPressureBySource = new Map();
+    /**
+     * Map of item id → source recorded at filter time, so a later
+     * `recordRetrieval(itemId)` call can credit the right source even
+     * when the agent only knows the item id. Bounded; oldest entries
+     * evicted via the same `maxHistory` knob.
+     */
+    itemSourceMap = new Map();
+    constructor(policy = {}) {
+        this.policy = this.validatePolicy({ ...types_1.DEFAULT_NUTRITION_POLICY, ...policy });
+    }
+    validatePolicy(policy) {
+        const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+        if (!Number.isInteger(policy.maxContextTokens) || policy.maxContextTokens <= 0) {
+            throw new Error('Aahar: maxContextTokens must be a positive integer');
+        }
+        if (!finite(policy.relevanceThreshold) || policy.relevanceThreshold < 0 || policy.relevanceThreshold > 1) {
+            throw new Error('Aahar: relevanceThreshold must be a finite number in [0,1]');
+        }
+        if (!finite(policy.freshnessWindowSec) || policy.freshnessWindowSec <= 0) {
+            throw new Error('Aahar: freshnessWindowSec must be a positive finite number');
+        }
+        if (!Number.isInteger(policy.maxContextItems) || policy.maxContextItems <= 0) {
+            throw new Error('Aahar: maxContextItems must be a positive integer');
+        }
+        if (!finite(policy.targetSignalToNoise) || policy.targetSignalToNoise < 0 || policy.targetSignalToNoise > 1) {
+            throw new Error('Aahar: targetSignalToNoise must be a finite number in [0,1]');
+        }
+        if (policy.maxHistory !== undefined && (!Number.isInteger(policy.maxHistory) || policy.maxHistory < 0)) {
+            throw new Error('Aahar: maxHistory must be a non-negative integer if set');
+        }
+        if (policy.temporalIntent !== undefined &&
+            policy.temporalIntent !== 'recent' &&
+            policy.temporalIntent !== 'historical' &&
+            policy.temporalIntent !== 'any') {
+            throw new Error("Aahar: temporalIntent must be 'recent' | 'historical' | 'any' if set");
+        }
+        if (policy.deduplicationThreshold !== undefined) {
+            if (!finite(policy.deduplicationThreshold) || policy.deduplicationThreshold <= 0 || policy.deduplicationThreshold > 1) {
+                throw new Error('Aahar: deduplicationThreshold must be a finite number in (0,1] if set');
+            }
+        }
+        if (policy.diversityWeight !== undefined) {
+            if (!finite(policy.diversityWeight) || policy.diversityWeight < 0 || policy.diversityWeight > 1) {
+                throw new Error('Aahar: diversityWeight must be a finite number in [0,1] if set');
+            }
+        }
+        return policy;
+    }
+    enforceHistoryLimit() {
+        const cap = this.policy.maxHistory ?? 0;
+        if (cap > 0 && this.history.length > cap) {
+            this.history.splice(0, this.history.length - cap);
+        }
+    }
+    // ── Core: Filter & Curate Context ────────────────────────────────────────
+    /**
+     * Reject items whose numeric fields are non-finite or out of range so
+     * malformed callers can't bypass token budgets (negative `tokenCount`),
+     * dominate ranking (`Infinity` relevance), or poison sorting (`NaN`
+     * freshness). Throws an Error naming the offending field; callers should
+     * validate at their boundary if they need lenient handling.
+     */
+    static assertValidItem(item) {
+        const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+        if (!finite(item.relevanceScore) || item.relevanceScore < 0 || item.relevanceScore > 1) {
+            throw new Error(`Aahar: invalid relevanceScore ${item.relevanceScore} on item ${item.id} (must be a finite number in [0,1])`);
+        }
+        if (!finite(item.freshness)) {
+            throw new Error(`Aahar: invalid freshness ${item.freshness} on item ${item.id} (must be a finite Unix-seconds timestamp)`);
+        }
+        if (!finite(item.tokenCount) || item.tokenCount < 0 || !Number.isInteger(item.tokenCount)) {
+            throw new Error(`Aahar: invalid tokenCount ${item.tokenCount} on item ${item.id} (must be a non-negative integer)`);
+        }
+        if (item.trustScore !== undefined && (!finite(item.trustScore) || item.trustScore < 0 || item.trustScore > 1)) {
+            throw new Error(`Aahar: invalid trustScore ${item.trustScore} on item ${item.id} (must be a finite number in [0,1] if set)`);
+        }
+    }
+    /**
+     * Filter incoming context items based on nutrition policy.
+     * This is the primary "feeding" function — it ensures the agent
+     * only receives high-quality, relevant, fresh information.
+     *
+     * Validates each item up-front and throws on malformed numerics. The
+     * validation is a SAFETY GATE: silently accepting `tokenCount: -100000`
+     * or `relevanceScore: Infinity` would let a buggy/malicious caller
+     * bypass the token budget or dominate prioritization.
+     *
+     * When `options.query` is supplied, Aahar computes BM25 and entity-
+     * overlap signals against the query and fuses them with the caller's
+     * `relevanceScore` via Reciprocal Rank Fusion. The fused score replaces
+     * the bare relevance component of the per-item composite score but does
+     * NOT bypass the `relevanceThreshold` gate — the caller's authoritative
+     * relevance signal still decides admission. Omitting `options` is
+     * byte-for-byte equivalent to the previous single-argument signature.
+     */
+    filter(items, options) {
+        for (const item of items)
+            Aahar.assertValidItem(item);
+        this.assertValidOptions(options);
+        const nowSec = Date.now() / 1000;
+        const fusion = this.computeFusion(items, options?.query);
+        // Score and sort. When fusion was computed, pass each item's fused
+        // score through; otherwise the scoring degenerates to the legacy path.
+        const scored = items.map((item, i) => ({
+            item,
+            score: this.scoreItem(item, nowSec, fusion ? fusion[i] : undefined),
+            index: i,
+        }));
+        // Tier-aware ordering: 'always' first, then 'on-demand', then 'rare',
+        // and within each tier sort by composite score. This guarantees a
+        // 'rare' item with high relevance is dropped before an 'always'
+        // item with low relevance when the budget is tight.
+        const tierRank = (t) => t === 'always' ? 0 : t === 'rare' ? 2 : 1;
+        scored.sort((a, b) => {
+            const tr = tierRank(a.item.tier) - tierRank(b.item.tier);
+            if (tr !== 0)
+                return tr;
+            return b.score - a.score;
+        });
+        const rejected = [];
+        // Optional dedup pre-pass: collapse near-duplicate content before the
+        // packer runs so the token budget isn't burned on two copies of the
+        // same thing.
+        const survivors = this.policy.deduplicateNearDuplicates
+            ? this.deduplicate(scored, rejected)
+            : scored;
+        // Pack into the token budget. Greedy top-K by default; MMR-aware when
+        // `diversityWeight > 0` (coverage over redundancy).
+        const honorFreshnessGate = (this.policy.temporalIntent ?? 'recent') === 'recent';
+        const lambda = this.policy.diversityWeight ?? 0;
+        const accepted = lambda > 0
+            ? this.packWithMMR(survivors, lambda, nowSec, honorFreshnessGate, rejected)
+            : this.packGreedy(survivors, nowSec, honorFreshnessGate, rejected);
+        const totalTokens = accepted.reduce((s, i) => s + i.tokenCount, 0);
+        const qualityScore = accepted.length > 0
+            ? accepted.reduce((sum, i) => sum + i.relevanceScore, 0) / accepted.length
+            : 0;
+        // Track source for every input item so a later `recordRetrieval(id)`
+        // can credit the right source's pressure counter.
+        for (const i of items)
+            this.itemSourceMap.set(i.id, i.source);
+        // Tier breakdown — only populated if at least one item carried a
+        // tier hint (otherwise it's noise).
+        const anyTiered = items.some((i) => i.tier !== undefined);
+        let tierBreakdown;
+        if (anyTiered) {
+            tierBreakdown = {
+                always: { accepted: 0, rejected: 0 },
+                'on-demand': { accepted: 0, rejected: 0 },
+                rare: { accepted: 0, rejected: 0 },
+            };
+            for (const i of accepted) {
+                const t = i.tier ?? 'on-demand';
+                tierBreakdown[t].accepted += 1;
+            }
+            for (const i of rejected) {
+                const t = i.tier ?? 'on-demand';
+                tierBreakdown[t].rejected += 1;
+            }
+        }
+        // Omission marker: synthetic ContextItem so the agent sees an
+        // explicit `[ojas:omitted N items: reason1, reason2]` line at the
+        // tail of `accepted`.
+        let finalAccepted = accepted;
+        if (options?.emitOmissionMarker && rejected.length > 0) {
+            const reasonCounts = new Map();
+            for (const r of rejected) {
+                const key = r.tier === 'rare' ? 'low-tier' : 'budget-or-relevance';
+                reasonCounts.set(key, (reasonCounts.get(key) ?? 0) + 1);
+            }
+            const reasons = Array.from(reasonCounts.entries())
+                .map(([k, n]) => `${n} ${k}`)
+                .join(', ');
+            const marker = {
+                id: `aahar-omitted-${Date.now()}`,
+                content: `[ojas:omitted ${rejected.length} items: ${reasons}]`,
+                source: 'aahar/omission',
+                relevanceScore: 0,
+                freshness: 1,
+                tokenCount: 0, // synthetic, doesn't burn budget
+            };
+            finalAccepted = [...accepted, marker];
+        }
+        const result = {
+            accepted: finalAccepted,
+            rejected,
+            totalTokens,
+            qualityScore,
+            ...(tierBreakdown ? { tierBreakdown } : {}),
+        };
+        this.history.push(result);
+        this.enforceHistoryLimit();
+        return result;
+    }
+    // ── Adaptive compression (Block 4 — Aahar upgrades) ──────────────────────
+    /**
+     * Record that the agent fetched (or had to re-fetch) the named item.
+     * Drives adaptive compression: a source whose items are fetched
+     * repeatedly is one whose relevance was likely underestimated, so
+     * subsequent `filter()` calls soften the threshold for that source.
+     *
+     * Cheap, append-only. The caller doesn't need the item itself — Aahar
+     * uses the `id → source` mapping captured during the most recent
+     * `filter()` call. Unknown ids are silently ignored.
+     */
+    recordRetrieval(itemId) {
+        const source = this.itemSourceMap.get(itemId);
+        if (!source)
+            return;
+        this.retrievalPressureBySource.set(source, (this.retrievalPressureBySource.get(source) ?? 0) + 1);
+    }
+    /**
+     * Effective relevance threshold for `source`, after applying any
+     * accumulated retrieval pressure. Returns the base policy threshold
+     * unmodified when there is no pressure recorded. Each retrieval
+     * subtracts `0.02` from the threshold, floored at `0`. Used by
+     * `scoreItem` / `passesGate` callers; exposed for tests + diagnostics.
+     */
+    getEffectiveThreshold(source) {
+        const base = this.policy.relevanceThreshold;
+        const pressure = this.retrievalPressureBySource.get(source) ?? 0;
+        if (pressure === 0)
+            return base;
+        return Math.max(0, base - pressure * 0.02);
+    }
+    /** Reset retrieval-pressure counters. Useful for tests + diagnostics. */
+    resetRetrievalPressure() {
+        this.retrievalPressureBySource.clear();
+    }
+    /** Snapshot of retrieval pressure per source (read-only view). */
+    getRetrievalPressure() {
+        return new Map(this.retrievalPressureBySource);
+    }
+    // ── Lazy / on-demand content resolution ─────────────────────────────────
+    /**
+     * Walk `accepted` items, and for any that carry a `resolveContent`
+     * function, await the resolver and replace `content` with the
+     * resolved string. Items whose resolver throws are dropped from the
+     * returned array — callers don't want a half-resolved bundle.
+     *
+     * Useful when the upstream retriever produces lightweight handles
+     * (id + scoring hints) and the actual content is expensive to
+     * fetch. `filter()` runs its full ranking + budget enforcement on
+     * the placeholder content; only the items that survive into
+     * `accepted` pay the resolution cost.
+     *
+     * Items without a resolver are passed through untouched. Returns a
+     * new array — the input is not mutated.
+     */
+    async materialise(accepted) {
+        const out = [];
+        for (const item of accepted) {
+            if (typeof item.resolveContent !== 'function') {
+                out.push(item);
+                continue;
+            }
+            try {
+                const resolved = await item.resolveContent();
+                if (typeof resolved !== 'string') {
+                    // A non-string resolver result is treated as a resolution failure
+                    // — silently drop rather than ship corrupt content.
+                    continue;
+                }
+                // Spread to a new object so the caller can keep the original handle.
+                const { resolveContent: _omit, ...rest } = item;
+                void _omit;
+                out.push({ ...rest, content: resolved });
+            }
+            catch {
+                // Resolver throw → drop the item from the materialised set.
+            }
+        }
+        return out;
+    }
+    // ── Options validation ──────────────────────────────────────────────────
+    assertValidOptions(options) {
+        if (options === undefined)
+            return;
+        if (options.query !== undefined && typeof options.query !== 'string') {
+            throw new Error('Aahar: options.query must be a string if provided');
+        }
+    }
+    // ── Query-aware fusion (BM25 + entity overlap + caller relevance) ───────
+    /**
+     * Compute a Reciprocal-Rank-Fusion score per item over three lexical
+     * signals computed against `query`:
+     *   - BM25 over the local item corpus,
+     *   - count of overlapping entity tokens with the query,
+     *   - caller-supplied `relevanceScore`.
+     * Returns `null` when no query is supplied (or the query is empty after
+     * trimming) so the caller falls back to legacy scoring.
+     */
+    computeFusion(items, query) {
+        const q = query?.trim();
+        if (!q || items.length === 0)
+            return null;
+        const queryTokens = (0, scoring_1.tokenize)(q);
+        const queryEntities = (0, scoring_1.extractEntities)(q);
+        const docTokens = items.map((it) => (0, scoring_1.tokenize)(it.content));
+        const bm25 = (0, scoring_1.bm25Scores)(queryTokens, docTokens);
+        const entityOverlap = items.map((it) => {
+            const ents = (0, scoring_1.extractEntities)(it.content);
+            let n = 0;
+            for (const e of queryEntities)
+                if (ents.has(e))
+                    n++;
+            return n;
+        });
+        const relevanceVals = items.map((it) => it.relevanceScore);
+        const ranks = [
+            (0, scoring_1.scoresToRanks)(bm25),
+            (0, scoring_1.scoresToRanks)(entityOverlap),
+            (0, scoring_1.scoresToRanks)(relevanceVals),
+        ];
+        const fused = (0, scoring_1.rrfFuse)(ranks);
+        // Normalise to [0, 1] so the fused number plays nicely with the rest
+        // of the composite score which is also in [0, 1] per-component.
+        const maxFused = fused.reduce((m, v) => (v > m ? v : m), 0);
+        if (maxFused <= 0)
+            return fused.map(() => 0);
+        return fused.map((v) => v / maxFused);
+    }
+    // ── Dedup pre-pass ──────────────────────────────────────────────────────
+    /**
+     * Collapse near-duplicates by shingle Jaccard ≥ `deduplicationThreshold`.
+     * The first item encountered (highest-scored, since `scored` is already
+     * sorted descending) wins; later near-duplicates go to `rejected`.
+     */
+    deduplicate(scored, rejected) {
+        const threshold = this.policy.deduplicationThreshold ?? 0.85;
+        const kept = [];
+        const keptShingles = [];
+        for (const entry of scored) {
+            const sh = (0, scoring_1.shingles)(entry.item.content);
+            let isDup = false;
+            for (const ks of keptShingles) {
+                if ((0, scoring_1.jaccard)(sh, ks) >= threshold) {
+                    isDup = true;
+                    break;
+                }
+            }
+            if (isDup) {
+                rejected.push(entry.item);
+            }
+            else {
+                kept.push(entry);
+                keptShingles.push(sh);
+            }
+        }
+        return kept;
+    }
+    // ── Packing strategies ──────────────────────────────────────────────────
+    /**
+     * Greedy top-K packing (legacy behaviour). Items are already sorted by
+     * composite score; admit them in order while they pass the gates and
+     * the running token budget has room.
+     */
+    packGreedy(sortedScored, nowSec, honorFreshnessGate, rejected) {
+        const accepted = [];
+        let totalTokens = 0;
+        for (const { item } of sortedScored) {
+            // Adaptive-compression: per-source threshold falls as the agent
+            // keeps re-fetching items from that source.
+            const effectiveThreshold = this.getEffectiveThreshold(item.source);
+            const passesRelevance = item.relevanceScore >= effectiveThreshold;
+            const passesFreshness = !honorFreshnessGate || (nowSec - item.freshness) < this.policy.freshnessWindowSec;
+            const passesTokenBudget = (totalTokens + item.tokenCount) <= this.policy.maxContextTokens;
+            const passesItemLimit = accepted.length < this.policy.maxContextItems;
+            if (passesRelevance && passesFreshness && passesTokenBudget && passesItemLimit) {
+                accepted.push(item);
+                totalTokens += item.tokenCount;
+            }
+            else {
+                rejected.push(item);
+            }
+        }
+        return accepted;
+    }
+    /**
+     * Maximal Marginal Relevance packing. For each slot, pick the candidate
+     * that maximises `(1 - λ)*score - λ*maxSim(c, accepted)` where sim is
+     * cosine over token bags. λ=0 reduces to greedy; λ=1 picks purely for
+     * diversity. Items failing the relevance or freshness gates are routed
+     * to `rejected` up-front so MMR only chooses among legitimate
+     * candidates.
+     */
+    packWithMMR(sortedScored, lambda, nowSec, honorFreshnessGate, rejected) {
+        // First, partition by gates. Pre-tokenise + pre-bag once so the inner
+        // MMR loop is O(K*N) cosine ops with cached bags instead of
+        // re-tokenising on every comparison.
+        const candidates = [];
+        for (const { item, score } of sortedScored) {
+            const effectiveThreshold = this.getEffectiveThreshold(item.source);
+            const passesRelevance = item.relevanceScore >= effectiveThreshold;
+            const passesFreshness = !honorFreshnessGate || (nowSec - item.freshness) < this.policy.freshnessWindowSec;
+            if (!passesRelevance || !passesFreshness) {
+                rejected.push(item);
+                continue;
+            }
+            candidates.push({ item, score, bag: (0, scoring_1.buildBag)((0, scoring_1.tokenize)(item.content)) });
+        }
+        const accepted = [];
+        const acceptedBags = [];
+        let totalTokens = 0;
+        while (candidates.length > 0 && accepted.length < this.policy.maxContextItems) {
+            // Find the candidate maximising the MMR objective.
+            let bestIdx = -1;
+            let bestMmr = Number.NEGATIVE_INFINITY;
+            for (let i = 0; i < candidates.length; i++) {
+                const c = candidates[i];
+                let maxSim = 0;
+                for (const ab of acceptedBags) {
+                    const s = (0, scoring_1.bagCosine)(c.bag, ab);
+                    if (s > maxSim)
+                        maxSim = s;
+                }
+                const mmr = (1 - lambda) * c.score - lambda * maxSim;
+                if (mmr > bestMmr) {
+                    bestMmr = mmr;
+                    bestIdx = i;
+                }
+            }
+            if (bestIdx < 0)
+                break;
+            const chosen = candidates[bestIdx];
+            candidates.splice(bestIdx, 1);
+            if (totalTokens + chosen.item.tokenCount <= this.policy.maxContextTokens) {
+                accepted.push(chosen.item);
+                acceptedBags.push(chosen.bag);
+                totalTokens += chosen.item.tokenCount;
+            }
+            else {
+                rejected.push(chosen.item);
+            }
+        }
+        // Anything left over after the item-limit fired is rejected too.
+        for (const c of candidates)
+            rejected.push(c.item);
+        return accepted;
+    }
+    // ── Context Quality Scoring ──────────────────────────────────────────────
+    /**
+     * Score a single context item. Higher = better nutrition.
+     *
+     * `fusionOverride`, when provided, replaces the bare `relevanceScore`
+     * term in the composite. Callers pass it when query-aware fusion has
+     * been computed for the whole batch (see `computeFusion`). The other
+     * components (freshness, tokenPenalty) and their weights are unchanged
+     * so the score remains on the same [0, 1]-ish scale as before.
+     *
+     * `temporalIntent` reshapes the freshness component:
+     *   - `'recent'` (default): exponential decay favours new items.
+     *   - `'any'`: freshness held at 0.5 (neutral).
+     *   - `'historical'`: invert the decay so older items rank higher.
+     */
+    scoreItem(item, nowSec, fusionOverride) {
+        const ageSec = Math.max(0, nowSec - item.freshness);
+        const intent = this.policy.temporalIntent ?? 'recent';
+        let freshness;
+        if (intent === 'any') {
+            freshness = 0.5;
+        }
+        else if (intent === 'historical') {
+            freshness = 1 - Math.exp(-ageSec / this.policy.freshnessWindowSec);
+        }
+        else {
+            freshness = Math.exp(-ageSec / this.policy.freshnessWindowSec);
+        }
+        const tokenPenalty = item.tokenCount > this.policy.maxContextTokens * 0.5
+            ? 0.5
+            : 1.0;
+        const relevanceComponent = fusionOverride ?? item.relevanceScore;
+        return (relevanceComponent * 0.6) + (freshness * 0.3) + (tokenPenalty * 0.1);
+    }
+    // ── Cognitive Load Assessment ────────────────────────────────────────────
+    /**
+     * Measure current cognitive load based on context composition.
+     * Returns 0 (no load) to 1 (overloaded).
+     */
+    measureCognitiveLoad(activeContext) {
+        for (const item of activeContext)
+            Aahar.assertValidItem(item);
+        if (activeContext.length === 0)
+            return 0;
+        const totalTokens = activeContext.reduce((s, i) => s + i.tokenCount, 0);
+        const tokenLoad = totalTokens / this.policy.maxContextTokens;
+        const itemLoad = activeContext.length / this.policy.maxContextItems;
+        const noiseLoad = 1 - this.measureSignalToNoise(activeContext);
+        return clamp((tokenLoad * 0.4) + (itemLoad * 0.3) + (noiseLoad * 0.3));
+    }
+    // ── Signal-to-Noise Ratio ────────────────────────────────────────────────
+    /**
+     * Compute signal-to-noise ratio for a set of context items.
+     * Higher = cleaner cognitive input.
+     */
+    measureSignalToNoise(items) {
+        for (const item of items)
+            Aahar.assertValidItem(item);
+        if (items.length === 0)
+            return 0;
+        const signal = items.filter((i) => i.relevanceScore >= this.policy.relevanceThreshold).length;
+        return signal / items.length;
+    }
+    // ── Token Efficiency ─────────────────────────────────────────────────────
+    /**
+     * Compute token efficiency: how many tokens are high-signal vs wasted.
+     */
+    measureTokenEfficiency(items) {
+        for (const item of items)
+            Aahar.assertValidItem(item);
+        if (items.length === 0)
+            return 0;
+        const totalTokens = items.reduce((s, i) => s + i.tokenCount, 0);
+        if (totalTokens === 0)
+            return 0;
+        const signalTokens = items
+            .filter((i) => i.relevanceScore >= this.policy.relevanceThreshold)
+            .reduce((s, i) => s + i.tokenCount, 0);
+        return signalTokens / totalTokens;
+    }
+    // ── Attention Prioritization ─────────────────────────────────────────────
+    /**
+     * Re-rank context items by cognitive priority.
+     * Returns items ordered by what the agent should attend to first.
+     *
+     * When `options.query` is supplied, ranking incorporates the same
+     * BM25 + entity-overlap + RRF fusion as `filter()`. Omitting `options`
+     * preserves the previous single-argument behaviour.
+     */
+    prioritize(items, options) {
+        for (const item of items)
+            Aahar.assertValidItem(item);
+        this.assertValidOptions(options);
+        const nowSec = Date.now() / 1000;
+        const fusion = this.computeFusion(items, options?.query);
+        return [...items]
+            .map((item, i) => ({ item, score: this.scoreItem(item, nowSec, fusion ? fusion[i] : undefined) }))
+            .sort((a, b) => b.score - a.score)
+            .map((e) => e.item);
+    }
+    // ── Full Nutrition Health Assessment ─────────────────────────────────────
+    /**
+     * Produce a complete nutrition health report for current context.
+     */
+    assess(activeContext) {
+        for (const item of activeContext)
+            Aahar.assertValidItem(item);
+        const snr = this.measureSignalToNoise(activeContext);
+        const load = this.measureCognitiveLoad(activeContext);
+        const efficiency = this.measureTokenEfficiency(activeContext);
+        return {
+            contextQuality: healthScore(snr, 'aahar.signalToNoise'),
+            cognitiveLoad: healthScore(1 - load, 'aahar.cognitiveLoad'),
+            attentionFocus: healthScore(activeContext.length > 0
+                ? activeContext.slice(0, 3).reduce((s, i) => s + i.relevanceScore, 0) / Math.min(3, activeContext.length)
+                : 0, 'aahar.attentionFocus'),
+            signalToNoise: snr,
+            tokenEfficiency: efficiency,
+        };
+    }
+    // ── Recommendations ──────────────────────────────────────────────────────
+    /**
+     * Generate nutrition health recommendations.
+     */
+    recommend(activeContext) {
+        const recs = [];
+        const health = this.assess(activeContext);
+        if (health.signalToNoise < this.policy.targetSignalToNoise) {
+            recs.push({
+                module: 'aahar',
+                severity: health.signalToNoise < 0.3 ? 'critical' : 'warning',
+                message: `Signal-to-noise ratio is ${(health.signalToNoise * 100).toFixed(1)}% — below target of ${(this.policy.targetSignalToNoise * 100).toFixed(1)}%`,
+                action: 'Filter low-relevance context items and refresh stale data.',
+            });
+        }
+        if (health.cognitiveLoad.value < 0.3) {
+            recs.push({
+                module: 'aahar',
+                severity: 'critical',
+                message: 'Cognitive load is dangerously high — context overload detected.',
+                action: 'Reduce active context size and remove redundant items.',
+            });
+        }
+        if (health.tokenEfficiency < 0.5) {
+            recs.push({
+                module: 'aahar',
+                severity: 'warning',
+                message: `Token efficiency at ${(health.tokenEfficiency * 100).toFixed(1)}% — significant waste detected.`,
+                action: 'Trim low-value context items to reclaim token budget.',
+            });
+        }
+        if (activeContext.length > this.policy.maxContextItems * 0.9) {
+            recs.push({
+                module: 'aahar',
+                severity: 'warning',
+                message: 'Approaching maximum context item limit.',
+                action: 'Consolidate or evict least relevant items.',
+            });
+        }
+        if (recs.length === 0) {
+            recs.push({
+                module: 'aahar',
+                severity: 'info',
+                message: 'Cognitive nutrition is healthy.',
+            });
+        }
+        return recs;
+    }
+    // ── Policy Management ────────────────────────────────────────────────────
+    getPolicy() {
+        return { ...this.policy };
+    }
+    updatePolicy(updates) {
+        this.policy = this.validatePolicy({ ...this.policy, ...updates });
+        this.enforceHistoryLimit();
+    }
+    getHistory() {
+        return [...this.history];
+    }
+}
+exports.Aahar = Aahar;
+//# sourceMappingURL=index.js.map