pi-mega-compact 0.8.21 → 0.8.23

package/dist/src/importance.js

@@ -0,0 +1,197 @@
+/** The 8 content/item types that drive the type multiplier. */
+export var ContextItemType;
+(function (ContextItemType) {
+    ContextItemType["UserMessage"] = "user_message";
+    ContextItemType["AssistantMessage"] = "assistant_message";
+    ContextItemType["SystemMessage"] = "system_message";
+    ContextItemType["CodeBlock"] = "code_block";
+    ContextItemType["Error"] = "error";
+    ContextItemType["Decision"] = "decision";
+    ContextItemType["FileModification"] = "file_modification";
+    ContextItemType["ToolExecution"] = "tool_execution";
+})(ContextItemType || (ContextItemType = {}));
+/**
+ * Default type multipliers (ported from the Rust reference
+ * `router/src/context/importance.rs`). Decisions (2.5x) and errors (2.0x)
+ * dominate; system/filler (0.5x) sinks.
+ */
+export const DEFAULT_MULTIPLIERS = {
+    [ContextItemType.UserMessage]: 1.5,
+    [ContextItemType.AssistantMessage]: 1.0,
+    [ContextItemType.SystemMessage]: 0.5,
+    [ContextItemType.CodeBlock]: 1.2,
+    [ContextItemType.Error]: 2.0,
+    [ContextItemType.Decision]: 2.5,
+    [ContextItemType.FileModification]: 1.8,
+    [ContextItemType.ToolExecution]: 1.3,
+};
+/**
+ * Age decay: fraction to SUBTRACT from the score.
+ * Formula: `min(maxDecay, (ageMs / 3_600_000) * decayRatePerHour)`.
+ * 0 = fresh, 0.7 = very old. At 14h with 0.05/hr: 14 * 0.05 = 0.70 (capped).
+ */
+export function ageDecay(itemAgeMs, decayRatePerHour = 0.05, maxDecay = 0.7) {
+    if (itemAgeMs <= 0)
+        return 0;
+    const hours = itemAgeMs / 3_600_000;
+    return Math.min(maxDecay, hours * decayRatePerHour);
+}
+/** Recency boost: 1.2 if `ageMs < thresholdMs` (default 5min), else 1.0. */
+export function recencyBoost(ageMs, thresholdMs = 300_000) {
+    return ageMs < thresholdMs ? 1.2 : 1.0;
+}
+/**
+ * Retention boost: 3.0 if the user flagged the item, else 1.0.
+ * User-flagged items are also inferred by `detectItemType` returning
+ * Decision or Error.
+ */
+export function retentionBoost(userFlagged) {
+    return userFlagged ? 3.0 : 1.0;
+}
+/**
+ * Classify a content blob into a `ContextItemType`.
+ *
+ * Rules are ordered by priority — first match wins:
+ * 1. role === "tool" → ToolExecution
+ * 2. role === "custom" → SystemMessage
+ * 3. error-ish content → Error
+ * 4. decision-ish content → Decision
+ * 5. fenced code block (≥20 chars) → CodeBlock
+ * 6. file-modification verbs → FileModification
+ * 7. role === "user" → UserMessage
+ * 8. role === "assistant" → AssistantMessage
+ * 9. Fallback → AssistantMessage
+ */
+export function detectItemType(content, role) {
+    const c = content ?? "";
+    if (role === "tool")
+        return ContextItemType.ToolExecution;
+    if (role === "custom")
+        return ContextItemType.SystemMessage;
+    // (3) errors — traceback / panic / E#### / exception / failure / crash.
+    if (/error|exception|failure|crash|panic|traceback|E\d{4}/i.test(c)) {
+        return ContextItemType.Error;
+    }
+    // (4) decisions — "we decided", "going with", "switching to", etc.
+    if (/decided|we chose|going with|switching to|using .* instead|final decision|let's go with/i.test(c)) {
+        return ContextItemType.Decision;
+    }
+    // (5) fenced code block ≥20 chars.
+    if (/```[\s\S]{20,}/.test(c)) {
+        return ContextItemType.CodeBlock;
+    }
+    // (6) file modification verbs.
+    if (/(wrote|edited|created|modified|updated|patched)\s+\S+\.\w+/i.test(c)) {
+        return ContextItemType.FileModification;
+    }
+    if (role === "user")
+        return ContextItemType.UserMessage;
+    if (role === "assistant")
+        return ContextItemType.AssistantMessage;
+    // (9) Fallback.
+    return ContextItemType.AssistantMessage;
+}
+/**
+ * Composite score for a single item.
+ *
+ * Formula:
+ *   type = detectItemType(content, role)
+ *   rawMult = multipliers[type] ?? DEFAULT_MULTIPLIERS[type]
+ *   decay = ageDecay(now - timestamp, decayRatePerHour, maxDecay)
+ *   recency = recencyBoost(now - timestamp, recencyThresholdMs)
+ *   retention = retentionBoost(userFlagged)
+ *   finalScore = rawMult * (1 - decay) * recency * retention
+ *
+ * Clamps `finalScore` to a minimum of 0.01 (never zero, so an item is
+ * always a candidate unless explicitly filtered).
+ */
+export function score(item, now, multipliers, opts) {
+    const content = item.content ?? "";
+    // detectItemType expects the 4-role union; narrow defensively.
+    const role = (["user", "assistant", "tool", "custom"].includes(item.role)
+        ? item.role
+        : "assistant");
+    const type = detectItemType(content, role);
+    const rawMultiplier = multipliers?.[type] ?? DEFAULT_MULTIPLIERS[type];
+    const ageMs = Math.max(0, now - item.timestamp);
+    const decay = ageDecay(ageMs, opts?.decayRatePerHour, opts?.maxDecay);
+    const recency = recencyBoost(ageMs, opts?.recencyThresholdMs);
+    const retention = retentionBoost(item.userFlagged === true);
+    const finalScore = Math.max(0.01, rawMultiplier * (1 - decay) * recency * retention);
+    return {
+        id: item.id,
+        type,
+        content,
+        role,
+        timestamp: item.timestamp,
+        rawMultiplier,
+        ageDecay: decay,
+        recencyBoost: recency,
+        retentionBoost: retention,
+        finalScore,
+    };
+}
+/**
+ * Score cutoff at the `preserveRatio` percentile boundary.
+ *
+ * Sorts items by `finalScore` descending; returns the score at the
+ * `preserveRatio` quantile. Items with `finalScore >= threshold` are
+ * preserved.
+ *
+ * - `ratio = 1.0` → return 0 (preserve all)
+ * - `ratio = 0` → return Infinity (preserve none)
+ * - empty input → return Infinity
+ */
+export function preservationCutoff(items, preserveRatio) {
+    if (items.length === 0)
+        return Infinity;
+    if (preserveRatio >= 1)
+        return 0;
+    if (preserveRatio <= 0)
+        return Infinity;
+    // Sort descending; the top `preserveRatio` fraction is preserved.
+    const sorted = [...items].sort((a, b) => b.finalScore - a.finalScore);
+    // Index of the lowest-scoring item in the preserved set.
+    // ceil(N * ratio) - 1, clamped to [0, N-1].
+    const cutoffIdx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * preserveRatio) - 1));
+    return sorted[cutoffIdx].finalScore;
+}
+/**
+ * Select which items to preserve verbatim based on `preserveRatio`.
+ *
+ * Returns the IDs of items with `finalScore >= threshold`. The caller
+ * is responsible for excluding items inside the anchor window (the
+ * boundary guard already protects those).
+ */
+export function itemsToPreserve(items, preserveRatio) {
+    const threshold = preservationCutoff(items, preserveRatio);
+    const preservedIds = new Set(items.filter((i) => i.finalScore >= threshold).map((i) => i.id));
+    return {
+        preservedIds,
+        threshold,
+        totalScored: items.length,
+        totalPreserved: preservedIds.size,
+    };
+}
+/**
+ * Convenience: score a list of `EngineMessage`s in position order using
+ * approximate ages from their index (1 minute per position, oldest first).
+ * Real timestamps should be threaded through the extension adapter when
+ * available; this is the position-based fallback documented in S40B-2.
+ *
+ * The returned `ScoredItem[]` is in the SAME ORDER as the input — callers
+ * index back into `messages` by `id` (which is the stringified index).
+ */
+export function scoreEngineMessages(messages, now, multipliers, opts) {
+    return messages.map((m, i) => {
+        // Oldest message (i=0) is `messages.length` minutes ago; newest is 1 min.
+        const timestamp = now - (messages.length - i) * 60_000;
+        return score({
+            id: String(i),
+            content: m.text ?? "",
+            role: m.role,
+            timestamp,
+            userFlagged: false,
+        }, now, multipliers, opts);
+    });
+}

package/dist/src/importance.test.js

@@ -0,0 +1,372 @@
+/**
+ * importance.test.ts — S40A unit tests for the importance scoring engine.
+ *
+ * Covers all exports: ContextItemType, DEFAULT_MULTIPLIERS, detectItemType,
+ * ageDecay, recencyBoost, retentionBoost, score, preservationCutoff,
+ * itemsToPreserve, scoreEngineMessages.
+ *
+ * Determinism is enforced — same inputs MUST produce same outputs.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ContextItemType, DEFAULT_MULTIPLIERS, detectItemType, ageDecay, recencyBoost, retentionBoost, score, preservationCutoff, itemsToPreserve, scoreEngineMessages, } from "./importance.js";
+const NOW = 1_700_000_000_000; // fixed epoch ms for determinism
+// ---- S40A-1: types and enums ----
+test("ContextItemType enum has 8 variants with snake_case values", () => {
+    assert.equal(ContextItemType.UserMessage, "user_message");
+    assert.equal(ContextItemType.AssistantMessage, "assistant_message");
+    assert.equal(ContextItemType.SystemMessage, "system_message");
+    assert.equal(ContextItemType.CodeBlock, "code_block");
+    assert.equal(ContextItemType.Error, "error");
+    assert.equal(ContextItemType.Decision, "decision");
+    assert.equal(ContextItemType.FileModification, "file_modification");
+    assert.equal(ContextItemType.ToolExecution, "tool_execution");
+});
+// ---- S40A-2: DEFAULT_MULTIPLIERS ----
+test("DEFAULT_MULTIPLIERS matches the Rust reference values", () => {
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.UserMessage], 1.5);
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.AssistantMessage], 1.0);
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.SystemMessage], 0.5);
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.CodeBlock], 1.2);
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.Error], 2.0);
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.Decision], 2.5);
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.FileModification], 1.8);
+    assert.equal(DEFAULT_MULTIPLIERS[ContextItemType.ToolExecution], 1.3);
+});
+test("DEFAULT_MULTIPLIERS has an entry for every ContextItemType variant", () => {
+    for (const t of Object.values(ContextItemType)) {
+        assert.equal(typeof DEFAULT_MULTIPLIERS[t], "number", `missing multiplier for ${t}`);
+    }
+});
+// ---- S40A-3: ageDecay ----
+test("ageDecay: fresh (age=0) returns 0", () => {
+    assert.equal(ageDecay(0), 0);
+});
+test("ageDecay: 1 hour at 5%/hr returns 0.05", () => {
+    assert.equal(ageDecay(3_600_000), 0.05);
+});
+test("ageDecay: 14 hours caps at 0.7 (maxDecay)", () => {
+    assert.equal(ageDecay(14 * 3_600_000), 0.7);
+});
+test("ageDecay: beyond 14 hours stays capped at 0.7", () => {
+    assert.equal(ageDecay(100 * 3_600_000), 0.7);
+});
+test("ageDecay: negative age (future timestamp) returns 0", () => {
+    assert.equal(ageDecay(-5_000), 0);
+});
+test("ageDecay: custom rate and max override defaults", () => {
+    // 10h at 0.1/hr = 1.0 → capped at 0.8.
+    assert.equal(ageDecay(10 * 3_600_000, 0.1, 0.8), 0.8);
+    // 2h at 0.1/hr = 0.2.
+    assert.equal(ageDecay(2 * 3_600_000, 0.1, 0.8), 0.2);
+});
+// ---- S40A-4: recencyBoost + retentionBoost ----
+test("recencyBoost: <5min returns 1.2", () => {
+    assert.equal(recencyBoost(299_000), 1.2);
+});
+test("recencyBoost: >5min returns 1.0", () => {
+    assert.equal(recencyBoost(301_000), 1.0);
+});
+test("recencyBoost: exactly 5min (300_000ms) returns 1.0 (boundary)", () => {
+    assert.equal(recencyBoost(300_000), 1.0);
+});
+test("recencyBoost: custom threshold respected", () => {
+    assert.equal(recencyBoost(5000, 10_000), 1.2);
+    assert.equal(recencyBoost(11_000, 10_000), 1.0);
+});
+test("retentionBoost: flagged returns 3.0", () => {
+    assert.equal(retentionBoost(true), 3.0);
+});
+test("retentionBoost: unflagged returns 1.0", () => {
+    assert.equal(retentionBoost(false), 1.0);
+});
+// ---- S40A-5: detectItemType ----
+test("detectItemType: role=tool → ToolExecution (priority 1)", () => {
+    // Even if content looks like an error, tool role wins.
+    assert.equal(detectItemType("error: something failed", "tool"), ContextItemType.ToolExecution);
+});
+test("detectItemType: role=custom → SystemMessage (priority 2)", () => {
+    assert.equal(detectItemType("anything here", "custom"), ContextItemType.SystemMessage);
+});
+test("detectItemType: error content → Error", () => {
+    assert.equal(detectItemType("Error: ENOENT at src/config.ts:42", "assistant"), ContextItemType.Error);
+    assert.equal(detectItemType("Traceback (most recent call last)", "assistant"), ContextItemType.Error);
+    assert.equal(detectItemType("panic: runtime error", "assistant"), ContextItemType.Error);
+    assert.equal(detectItemType("E4030 connection refused", "assistant"), ContextItemType.Error);
+});
+test("detectItemType: decision content → Decision", () => {
+    assert.equal(detectItemType("we decided to use JWT auth", "assistant"), ContextItemType.Decision);
+    assert.equal(detectItemType("going with option B", "assistant"), ContextItemType.Decision);
+    assert.equal(detectItemType("let's go with the async approach", "assistant"), ContextItemType.Decision);
+    assert.equal(detectItemType("switching to a different database", "assistant"), ContextItemType.Decision);
+});
+test("detectItemType: fenced code block ≥20 chars → CodeBlock", () => {
+    const code = "```js\nconst x = 42;\nconst y = 'hello world';\n```";
+    assert.equal(detectItemType(code, "assistant"), ContextItemType.CodeBlock);
+});
+test("detectItemType: short fenced block (<20 chars) does NOT → CodeBlock", () => {
+    const short = "```\nshort\n```";
+    assert.notEqual(detectItemType(short, "assistant"), ContextItemType.CodeBlock);
+});
+test("detectItemType: file modification verbs → FileModification", () => {
+    assert.equal(detectItemType("edited src/config.ts to add a flag", "assistant"), ContextItemType.FileModification);
+    assert.equal(detectItemType("created README.md", "assistant"), ContextItemType.FileModification);
+    assert.equal(detectItemType("wrote tests/main.test.ts", "assistant"), ContextItemType.FileModification);
+});
+test("detectItemType: role=user → UserMessage", () => {
+    assert.equal(detectItemType("plain question", "user"), ContextItemType.UserMessage);
+});
+test("detectItemType: role=assistant → AssistantMessage", () => {
+    assert.equal(detectItemType("plain answer", "assistant"), ContextItemType.AssistantMessage);
+});
+test("detectItemType: fallback → AssistantMessage", () => {
+    // Unknown role with non-matching content falls back to AssistantMessage.
+    assert.equal(detectItemType("nothing matches here", "unknown"), ContextItemType.AssistantMessage);
+});
+test("detectItemType: empty string does not crash and falls back", () => {
+    assert.equal(detectItemType("", "user"), ContextItemType.UserMessage);
+    assert.equal(detectItemType("", "assistant"), ContextItemType.AssistantMessage);
+});
+test("detectItemType: priority — error before decision (first match wins)", () => {
+    // A message that contains BOTH "error" and "decided" — error wins (rule 3 before rule 4).
+    assert.equal(detectItemType("error: we decided to fail", "assistant"), ContextItemType.Error);
+});
+// ---- S40A-6: score ----
+test("score: fresh decision gets full multiplier (no decay, no recency/retention boost expected unless young)", () => {
+    const result = score({
+        id: "0",
+        content: "we decided to use JWT",
+        role: "assistant",
+        timestamp: NOW, // age 0
+    }, NOW);
+    assert.equal(result.type, ContextItemType.Decision);
+    assert.equal(result.rawMultiplier, 2.5);
+    assert.equal(result.ageDecay, 0);
+    assert.equal(result.recencyBoost, 1.2); // age 0 < 5min
+    assert.equal(result.retentionBoost, 1.0); // not userFlagged
+    // 2.5 * (1 - 0) * 1.2 * 1.0 = 3.0
+    assert.equal(result.finalScore, 3.0);
+});
+test("score: old decision decays", () => {
+    const tenHoursAgo = NOW - 10 * 3_600_000;
+    const result = score({
+        id: "1",
+        content: "we decided to use JWT",
+        role: "assistant",
+        timestamp: tenHoursAgo,
+    }, NOW);
+    // decay at 10h = 0.5; recency 1.0 (>5min); retention 1.0
+    // 2.5 * (1 - 0.5) * 1.0 * 1.0 = 1.25
+    assert.equal(result.ageDecay, 0.5);
+    assert.equal(result.recencyBoost, 1.0);
+    assert.equal(result.finalScore, 1.25);
+});
+test("score: userFlagged triples the result via retentionBoost", () => {
+    const flagged = score({
+        id: "2",
+        content: "we decided to use JWT",
+        role: "assistant",
+        timestamp: NOW,
+        userFlagged: true,
+    }, NOW);
+    const unflagged = score({
+        id: "3",
+        content: "we decided to use JWT",
+        role: "assistant",
+        timestamp: NOW,
+        userFlagged: false,
+    }, NOW);
+    // 3.0 / 1.0 retention ratio.
+    assert.equal(flagged.finalScore / unflagged.finalScore, 3.0);
+});
+test("score: clamps finalScore to minimum 0.01", () => {
+    // A system message (0.5x) at 14h+ (max decay 0.7) → 0.5 * 0.3 * 1.0 * 1.0 = 0.15. Above 0.01.
+    // Force below 0.01 with a custom multiplier of 0 and max decay.
+    const result = score({
+        id: "4",
+        content: "system filler",
+        role: "custom",
+        timestamp: NOW - 100 * 3_600_000,
+    }, NOW, { [ContextItemType.SystemMessage]: 0.01 }, { maxDecay: 0.99 });
+    // 0.01 * (1 - 0.99) * 1.0 * 1.0 = 0.0001 → clamped to 0.01.
+    assert.equal(result.finalScore, 0.01);
+});
+test("score: custom multipliers override DEFAULT_MULTIPLIERS", () => {
+    const result = score({
+        id: "5",
+        content: "we decided to use JWT",
+        role: "assistant",
+        timestamp: NOW,
+    }, NOW, { [ContextItemType.Decision]: 10.0 });
+    assert.equal(result.rawMultiplier, 10.0);
+    assert.equal(result.finalScore, 10.0 * 1.2); // 10 * (1-0) * 1.2 * 1.0
+});
+test("score: unknown role narrows to assistant defensively", () => {
+    const result = score({
+        id: "6",
+        content: "plain text",
+        role: "weird-role",
+        timestamp: NOW,
+    }, NOW);
+    assert.equal(result.role, "assistant");
+    assert.equal(result.type, ContextItemType.AssistantMessage);
+});
+test("score: undefined/null content does not crash", () => {
+    const r1 = score({ id: "a", content: undefined, role: "user", timestamp: NOW }, NOW);
+    const r2 = score({ id: "b", content: null, role: "assistant", timestamp: NOW }, NOW);
+    assert.equal(r1.type, ContextItemType.UserMessage);
+    assert.equal(r2.type, ContextItemType.AssistantMessage);
+    assert.equal(r1.content, "");
+    assert.equal(r2.content, "");
+});
+test("score: determinism — same inputs → same output", () => {
+    const item = {
+        id: "d1",
+        content: "we decided to use JWT",
+        role: "assistant",
+        timestamp: NOW - 3_600_000,
+    };
+    const a = score(item, NOW);
+    const b = score(item, NOW);
+    assert.deepEqual(a, b);
+});
+// ---- S40A-7: preservationCutoff + itemsToPreserve ----
+test("preservationCutoff: 10 items at ratio 0.3 → threshold is the 3rd-highest score", () => {
+    const items = Array.from({ length: 10 }, (_, i) => ({
+        id: String(i),
+        type: ContextItemType.AssistantMessage,
+        content: "",
+        role: "assistant",
+        timestamp: 0,
+        rawMultiplier: 1.0,
+        ageDecay: 0,
+        recencyBoost: 1.0,
+        retentionBoost: 1.0,
+        // scores 1.0, 2.0, ..., 10.0
+        finalScore: (i + 1) * 1.0,
+    }));
+    const threshold = preservationCutoff(items, 0.3);
+    // top 30% of 10 = 3 items; the 3rd highest is 8.0 (scores 10,9,8 preserved).
+    assert.equal(threshold, 8.0);
+});
+test("preservationCutoff: ratio=1.0 returns 0 (preserve all)", () => {
+    const items = [{ finalScore: 5, id: "x" }];
+    assert.equal(preservationCutoff(items, 1.0), 0);
+});
+test("preservationCutoff: ratio=0 returns Infinity (preserve none)", () => {
+    const items = [{ finalScore: 5, id: "x" }];
+    assert.equal(preservationCutoff(items, 0), Infinity);
+});
+test("preservationCutoff: empty input returns Infinity", () => {
+    assert.equal(preservationCutoff([], 0.5), Infinity);
+});
+test("itemsToPreserve: returns IDs at or above threshold", () => {
+    const items = Array.from({ length: 10 }, (_, i) => ({
+        id: String(i),
+        type: ContextItemType.AssistantMessage,
+        content: "",
+        role: "assistant",
+        timestamp: 0,
+        rawMultiplier: 1.0,
+        ageDecay: 0,
+        recencyBoost: 1.0,
+        retentionBoost: 1.0,
+        finalScore: (i + 1) * 1.0,
+    }));
+    const result = itemsToPreserve(items, 0.3);
+    assert.equal(result.totalScored, 10);
+    assert.equal(result.totalPreserved, 3);
+    assert.deepEqual([...result.preservedIds].sort(), ["7", "8", "9"]);
+});
+test("itemsToPreserve: ratio=1.0 preserves everything", () => {
+    const items = Array.from({ length: 5 }, (_, i) => ({
+        id: String(i),
+        type: ContextItemType.AssistantMessage,
+        content: "",
+        role: "assistant",
+        timestamp: 0,
+        rawMultiplier: 1.0,
+        ageDecay: 0,
+        recencyBoost: 1.0,
+        retentionBoost: 1.0,
+        finalScore: i + 1,
+    }));
+    const result = itemsToPreserve(items, 1.0);
+    assert.equal(result.totalPreserved, 5);
+});
+test("itemsToPreserve: ratio=0 preserves nothing", () => {
+    const items = Array.from({ length: 5 }, (_, i) => ({
+        id: String(i),
+        type: ContextItemType.AssistantMessage,
+        content: "",
+        role: "assistant",
+        timestamp: 0,
+        rawMultiplier: 1.0,
+        ageDecay: 0,
+        recencyBoost: 1.0,
+        retentionBoost: 1.0,
+        finalScore: i + 1,
+    }));
+    const result = itemsToPreserve(items, 0);
+    assert.equal(result.totalPreserved, 0);
+    assert.equal(result.threshold, Infinity);
+});
+test("itemsToPreserve: empty items returns empty set", () => {
+    const result = itemsToPreserve([], 0.5);
+    assert.equal(result.totalScored, 0);
+    assert.equal(result.totalPreserved, 0);
+    assert.equal(result.preservedIds.size, 0);
+});
+// ---- scoreEngineMessages: position-based age fallback ----
+test("scoreEngineMessages: assigns position-based timestamps (oldest first)", () => {
+    const messages = [
+        { role: "assistant", text: "we decided to use JWT" },
+        { role: "user", text: "ok" },
+        { role: "assistant", text: "edited src/config.ts" },
+    ];
+    const scored = scoreEngineMessages(messages, NOW);
+    assert.equal(scored.length, 3);
+    // Oldest (i=0) is `messages.length` minutes ago = 3 min.
+    assert.equal(scored[0].timestamp, NOW - 3 * 60_000);
+    // Newest (i=2) is 1 min ago.
+    assert.equal(scored[2].timestamp, NOW - 1 * 60_000);
+    // All recency-boosted (< 5 min).
+    assert.equal(scored[0].recencyBoost, 1.2);
+    assert.equal(scored[2].recencyBoost, 1.2);
+});
+test("scoreEngineMessages: preserves input order and ids are stringified indices", () => {
+    const messages = [
+        { role: "user", text: "first" },
+        { role: "user", text: "second" },
+    ];
+    const scored = scoreEngineMessages(messages, NOW);
+    assert.equal(scored[0].id, "0");
+    assert.equal(scored[1].id, "1");
+});
+test("scoreEngineMessages: empty input returns empty array", () => {
+    assert.deepEqual(scoreEngineMessages([], NOW), []);
+});
+test("scoreEngineMessages: determinism — same input → same output", () => {
+    const messages = [
+        { role: "assistant", text: "we decided to use JWT" },
+        { role: "user", text: "ok" },
+    ];
+    const a = scoreEngineMessages(messages, NOW);
+    const b = scoreEngineMessages(messages, NOW);
+    assert.deepEqual(a, b);
+});
+// ---- integration: a decision outsurvives filler ----
+test("integration: a decision is preserved over filler at the same age", () => {
+    // 10 messages, 1 decision (i=4) and 9 filler, all equally old.
+    const messages = Array.from({ length: 10 }, (_, i) => i === 4
+        ? { role: "assistant", text: "we decided to use JWT auth" }
+        : { role: "assistant", text: "ok, sounds good" });
+    const scored = scoreEngineMessages(messages, NOW - 10 * 60_000); // 10 min old → no recency boost
+    // decision rawMultiplier 2.5 vs filler 1.0; same decay, same recency.
+    const decision = scored[4];
+    const filler = scored[0];
+    assert.ok(decision.finalScore > filler.finalScore);
+    // top 20% → 2 items; the decision must be in the preserved set.
+    const result = itemsToPreserve(scored, 0.2);
+    assert.ok(result.preservedIds.has("4"), "decision must be preserved");
+});

package/dist/src/ratio.bench.test.js

@@ -17,7 +17,7 @@ import assert from "node:assert/strict";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { VectorStore, computeRegionHash } from "./vectorStore.js";
+import { VectorStore, computeRegionHash, vectorStats, vectorWasInjected, vectorMarkInjected, vectorTopSimilar } from "./vectorStore.js";
 import { findSuperseded } from "./supersede.js";
 import { autoCompactCheck, isChatty } from "./compact.js";
 import { extractiveSummarize } from "./extractive.js";
@@ -433,7 +433,7 @@ describe("Dedup Hit Rates by Similarity Level", () => {
         }
         // Check stats for each session
         for (const sid of sessionIds) {
-            const stats = store.stats(sid);
+            const stats = vectorStats(store, sid);
             console.log(`    ${sid}: ${stats.checkpointCount} checkpoint(s), dedup rate: ${(stats.dedupHitRate * 100).toFixed(0)}%`);
         }
     });
@@ -455,7 +455,7 @@ describe("Dedup Hit Rates by Similarity Level", () => {
         // Check stats across sessions
         let totalCheckpoints = 0;
         for (let i = 0; i < variations.length; i++) {
-            const stats = store.stats(`sess_l1_${i}`);
+            const stats = vectorStats(store, `sess_l1_${i}`);
             totalCheckpoints += stats.checkpointCount;
         }
         console.log(`    Near-duplicates added: ${variations.length}`);
@@ -480,7 +480,7 @@ describe("Dedup Hit Rates by Similarity Level", () => {
         }
         let totalCheckpoints = 0;
         for (let i = 0; i < variations.length; i++) {
-            const stats = store.stats(`sess_l1neg_${i}`);
+            const stats = vectorStats(store, `sess_l1neg_${i}`);
             totalCheckpoints += stats.checkpointCount;
         }
         const collapseRate = 1 - totalCheckpoints / variations.length;
@@ -509,7 +509,7 @@ describe("Dedup Hit Rates by Similarity Level", () => {
         }
         let totalCheckpoints = 0;
         for (let i = 0; i < paraphrases.length; i++) {
-            const stats = store.stats(`sess_l2_${i}`);
+            const stats = vectorStats(store, `sess_l2_${i}`);
             totalCheckpoints += stats.checkpointCount;
         }
         console.log(`    Paraphrases: ${paraphrases.length}`);
@@ -565,7 +565,7 @@ describe("Dedup Hit Rates by Similarity Level", () => {
                 timestamp: Date.now() + idx++ * 1000,
             });
         }
-        const stats = store.stats(dedupSession);
+        const stats = vectorStats(store, dedupSession);
         const totalAdded = 3 + 4 + 3;
         console.log(`    Total added: ${totalAdded}`);
         console.log(`    Checkpoints stored: ${stats.checkpointCount}`);
@@ -769,7 +769,7 @@ describe("Store Stats & Dedup Metrics", () => {
                 timestamp: Date.now() + 100 + i,
             });
         }
-        const stats = store.stats(session);
+        const stats = vectorStats(store, session);
         console.log(`    Total added: 5`);
         console.log(`    Checkpoints stored: ${stats.checkpointCount}`);
         console.log(`    Dedup hit rate: ${(stats.dedupHitRate * 100).toFixed(0)}%`);
@@ -782,15 +782,15 @@ describe("Store Stats & Dedup Metrics", () => {
         const id1 = "chkpt_inject_a";
         const id2 = "chkpt_inject_b";
         const sid = "sess_inject";
-        assert.equal(store.wasInjected(sid, id1), false, "Should not be injected initially");
-        store.markInjected(sid, id1);
-        assert.equal(store.wasInjected(sid, id1), true, "Should be injected after mark");
-        assert.equal(store.wasInjected(sid, id2), false, "Different ID should not be affected");
-        store.markInjected(sid, id2);
-        assert.equal(store.wasInjected(sid, id2), true, "Second ID should also be injected");
+        assert.equal(vectorWasInjected(store, sid, id1), false, "Should not be injected initially");
+        vectorMarkInjected(store, sid, id1);
+        assert.equal(vectorWasInjected(store, sid, id1), true, "Should be injected after mark");
+        assert.equal(vectorWasInjected(store, sid, id2), false, "Different ID should not be affected");
+        vectorMarkInjected(store, sid, id2);
+        assert.equal(vectorWasInjected(store, sid, id2), true, "Second ID should also be injected");
         // Idempotent
-        store.markInjected(sid, id1);
-        assert.equal(store.wasInjected(sid, id1), true, "Re-mark should be idempotent");
+        vectorMarkInjected(store, sid, id1);
+        assert.equal(vectorWasInjected(store, sid, id1), true, "Re-mark should be idempotent");
     });
     it("recall skips already-injected checkpoints", () => {
         const content = "Checkpoint for recall dedup sentinel test.";
@@ -813,7 +813,7 @@ describe("Store Stats & Dedup Metrics", () => {
         }, store);
         assert.ok(results1.hits.length >= 1, "First recall should return checkpoint");
         // Mark first hit as injected
-        store.markInjected(sid, results1.hits[0].checkpoint.checkpointId);
+        vectorMarkInjected(store, sid, results1.hits[0].checkpoint.checkpointId);
         // Second recall should skip it
         const results2 = recall({
             sessionId: sid,
@@ -859,13 +859,13 @@ describe("topSimilar Edge Cases & Coverage", () => {
             });
         }
         for (const n of [1, 3, 5, 10]) {
-            const results = store.topSimilar(sid, n);
+            const results = vectorTopSimilar(store, sid, n);
             assert.ok(results.length <= n, `topSimilar(${n}) returned ${results.length} results (should be <= ${n})`);
             console.log(`    n=${n}: ${results.length} results`);
         }
     });
     it("topSimilar returns empty for empty session", () => {
-        const results = store.topSimilar("sess_unknown_empty", 5);
+        const results = vectorTopSimilar(store, "sess_unknown_empty", 5);
         assert.equal(results.length, 0, "Empty session should return no results");
     });
 });