pi-mega-compact 0.8.21 → 0.8.22

package/dist/src/e2e.test.js

@@ -9,7 +9,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { VectorStore, computeRegionHash } from "./vectorStore.js";
+import { VectorStore, computeRegionHash, vectorList, vectorSemDedup, vectorWasInjected, vectorMarkInjected, vectorTopSimilar, vectorStats, vectorSearch } from "./vectorStore.js";
 import { compactSession, recall, supersededCount } from "./engine.js";
 import { loadDedupConfig } from "./config/dedup.js";
 import { defaultEmbedder } from "./embedder.js";
@@ -101,8 +101,8 @@ test("1. Full compaction pipeline: SUPERSEDE → COLLAPSE → CLUSTER", () => {
     // Verify: checkpoint persisted
     assert.ok(r.checkpointId, "checkpointId should be set");
     assert.match(r.checkpointId, /^chkpt_001$/);
-    // Verify: checkpoint is searchable via store.search()
-    const hits = s.search(SESS, "server.ts memory leak JWT auth", 5);
+    // Verify: checkpoint is searchable via vectorSearch(store, )
+    const hits = vectorSearch(s, SESS, "server.ts memory leak JWT auth", 5);
     assert.ok(hits.length > 0, "checkpoint should be searchable");
     assert.equal(hits[0].checkpoint.checkpointId, r.checkpointId);
 });
@@ -133,7 +133,7 @@ test("2. Multi-session dedup: identical content in same session detected by L0",
     assert.equal(rB.deduped, true, "second identical compaction should be deduped by L0");
     assert.ok(rB.dedupReason === "regionHash" || rB.dedupReason === "contentHash", `dedup reason should be L0 (regionHash or contentHash), got ${rB.dedupReason}`);
     // Search should still return the checkpoint
-    const hits = s.search("sess_multi_a", "database connection pooling", 5);
+    const hits = vectorSearch(s, "sess_multi_a", "database connection pooling", 5);
     assert.ok(hits.length > 0, "search returns the deduped result");
     assert.equal(hits[0].checkpoint.checkpointId, rA.checkpointId);
 });
@@ -162,7 +162,7 @@ test("3. Near-duplicate detection: L1 MinHash/LSH catches one-word edits that L0
     // L1 should catch the near-dup
     assert.equal(r2.deduped, true, "L1 should catch the near-duplicate");
     assert.equal(r2.reason, "l1MinHash", "dedup reason should be l1MinHash");
-    assert.equal(s.list(SESS).length, 1, "only one checkpoint stored");
+    assert.equal(vectorList(s, SESS).length, 1, "only one checkpoint stored");
 });
 test("3b. Negative: L1 does NOT collapse genuinely different content", () => {
     const s = store({ L2_ENABLED: false });
@@ -180,7 +180,7 @@ test("3b. Negative: L1 does NOT collapse genuinely different content", () => {
         timestamp: 2,
     });
     assert.equal(r2.deduped, false, "distinct content should not be deduped");
-    assert.equal(s.list(SESS).length, 2, "both checkpoints stored");
+    assert.equal(vectorList(s, SESS).length, 2, "both checkpoints stored");
 });
 // ---------------------------------------------------------------------------
 // 4. Semantic Dedup (L2 cosine)
@@ -208,7 +208,7 @@ test("4. Semantic dedup: L2 cosine catches highly similar content that L0/L1 mis
     // L2 semantic cosine should catch this high-similarity paraphrase
     assert.equal(r2.deduped, true, "L2 should catch the high-similarity paraphrase");
     assert.ok(r2.reason === "contentSimilarity" || r2.reason === "l1MinHash", `dedup reason should be L2 contentSimilarity or L1 l1MinHash, got ${r2.reason}`);
-    assert.equal(s.list(SESS).length, 1, "only one checkpoint after semantic dedup");
+    assert.equal(vectorList(s, SESS).length, 1, "only one checkpoint after semantic dedup");
 });
 test("4b. MMR diversifies search results", () => {
     const s = store();
@@ -230,7 +230,7 @@ test("4b. MMR diversifies search results", () => {
         });
     }
     // Search for parser-related content — should return relevant results
-    const hits = s.search(SESS, "parser tokenization source code files", 4);
+    const hits = vectorSearch(s, SESS, "parser tokenization source code files", 4);
     assert.ok(hits.length >= 1, "should return at least one result");
     // The top hit should be the parser checkpoint
     assert.ok(hits[0].checkpoint.summary.includes("topic_0"), "top hit is the parser topic");
@@ -255,20 +255,20 @@ test("5. SemDeDup offline cleanup: redundant rows marked removed, not deleted",
         { id: "chkpt_003", text: "the frontend uses a virtualized list for rendering large datasets efficiently", tok: 500, ts: 3 },
     ]);
     // Run SemDeDup with threshold that catches the near-identical pair
-    const removed = s.semDedup(SESS, 0.85);
+    const removed = vectorSemDedup(s, SESS, 0.85);
     assert.equal(removed, 1, "one redundant row should be marked removed");
     // Verify: the lower-tokenEstimate row is the one removed
-    const all = s.list(SESS);
+    const all = vectorList(s, SESS);
     const dropped = all.find((c) => c.dedupStatus === "removed");
     assert.ok(dropped, "a row should have dedup_status='removed'");
     assert.equal(dropped.checkpointId, "chkpt_001", "lower tokenEstimate row removed");
     assert.equal(dropped.dedupStatus, "removed");
     // Verify: search excludes removed rows (3 total, 1 removed → 2 active)
-    const hits = s.search(SESS, "cache parsed ast nodes frontend virtualized list", 10);
+    const hits = vectorSearch(s, SESS, "cache parsed ast nodes frontend virtualized list", 10);
     assert.equal(hits.length, 2, "search excludes the removed row, returns 2 active");
     assert.ok(hits.every((h) => h.checkpoint.dedupStatus !== "removed"), "no removed rows in search");
     // Verify: idempotent re-run removes nothing new
-    const secondRun = s.semDedup(SESS, 0.85);
+    const secondRun = vectorSemDedup(s, SESS, 0.85);
     assert.equal(secondRun, 0, "idempotent re-run removes nothing new");
     closeStore(dir);
 });
@@ -293,15 +293,15 @@ test("6. Recall + inline with dedup sentinel: injected checkpoints are skipped",
     assert.equal(first.hits.length, 1);
     // Mark it injected
     const cpId = first.hits[0].checkpoint.checkpointId;
-    s.markInjected(SESS, cpId);
+    vectorMarkInjected(s, SESS, cpId);
     // Recall again — should skip the injected checkpoint
     const second = recall({ sessionId: SESS, query: "vectorStore dedup cascade", limit: 5, skipInjected: true }, s);
     assert.equal(second.newHits.length, 0, "injected checkpoint should be skipped (dedup sentinel)");
     // Without skipInjected, hits still surface
     assert.equal(second.hits.length, 1, "hits still surface without skipInjected");
     // Verify wasInjected
-    assert.equal(s.wasInjected(SESS, cpId), true, "wasInjected returns true for injected checkpoint");
-    assert.equal(s.wasInjected(SESS, "chkpt_999"), false, "wasInjected returns false for non-injected");
+    assert.equal(vectorWasInjected(s, SESS, cpId), true, "wasInjected returns true for injected checkpoint");
+    assert.equal(vectorWasInjected(s, SESS, "chkpt_999"), false, "wasInjected returns false for non-injected");
 });
 // ---------------------------------------------------------------------------
 // 7. topSimilar
@@ -326,11 +326,11 @@ test("7. topSimilar: returns n most cosine-similar checkpoints", () => {
         });
     }
     // Call topSimilar(3)
-    const hits = s.topSimilar(SESS, 3);
+    const hits = vectorTopSimilar(s, SESS, 3);
     assert.ok(hits.length <= 3, "should respect n limit");
     assert.ok(hits.length > 0, "should return results");
     // Verify self-exclusion: the most recent checkpoint should not be in results
-    const all = s.list(SESS);
+    const all = vectorList(s, SESS);
     const ordered = [...all].sort((a, b) => a.checkpointId.localeCompare(b.checkpointId));
     const current = ordered[ordered.length - 1];
     assert.ok(!hits.some((h) => h.checkpoint.checkpointId === current.checkpointId), "current checkpoint excluded");
@@ -358,14 +358,14 @@ test("7b. topSimilar respects n limit strictly", () => {
             timestamp: i + 1,
         });
     }
-    const hits = s.topSimilar(SESS, 2);
+    const hits = vectorTopSimilar(s, SESS, 2);
     assert.equal(hits.length, 2, "n limit respected");
 });
 test("7c. topSimilar returns empty for sessions with 0 or 1 checkpoints", () => {
     const s = store();
-    assert.deepEqual(s.topSimilar("sess_empty", 5), []);
+    assert.deepEqual(vectorTopSimilar(s, "sess_empty", 5), []);
     s.add({ sessionId: "sess_one", summary: "solo", regionText: "only checkpoint here", timestamp: 1 });
-    assert.deepEqual(s.topSimilar("sess_one", 5), []);
+    assert.deepEqual(vectorTopSimilar(s, "sess_one", 5), []);
 });
 // ---------------------------------------------------------------------------
 // 8. Compression Round-Trip
@@ -390,7 +390,7 @@ test("8. Compression round-trip: decompression produces original content", () =>
         timestamp: 1,
     });
     // Retrieve and verify decompression
-    const cp = s.list(SESS)[0];
+    const cp = vectorList(s, SESS)[0];
     assert.ok(cp.compressedOriginal instanceof Buffer, "compressedOriginal is a Buffer");
     const restored = decompressSmart(cp.compressedOriginal).toString("utf-8");
     assert.equal(restored, originalText, "decompression produces the original content");
@@ -407,7 +407,7 @@ test("8b. Compression round-trip with different content sizes", () => {
     // Large text (>4KB → gzip level 6 or brotli)
     const large = "detailed region text with lots of context about the codebase. ".repeat(200);
     s.add({ sessionId: SESS, summary: "large", regionText: large, timestamp: 3 });
-    const checkpoints = s.list(SESS);
+    const checkpoints = vectorList(s, SESS);
     assert.equal(checkpoints.length, 3);
     // Verify each round-trips correctly
     const texts = [small, medium, large];
@@ -444,7 +444,7 @@ test("9. Store stats and metrics reflect actual state after compactions", () =>
     const r3 = compactSession({ sessionId: SESS, messages: conv3, keepFrom: 2, timestamp: 3 }, s);
     assert.equal(r3.deduped, false);
     // Get stats
-    const st = s.stats(SESS);
+    const st = vectorStats(s, SESS);
     assert.equal(st.checkpointCount, 3, "three checkpoints stored");
     assert.ok(st.totalTokenEstimate > 0, "totalTokenEstimate should be positive");
     assert.equal(st.lastCheckpointId, "chkpt_003", "last checkpoint id correct");
@@ -452,14 +452,14 @@ test("9. Store stats and metrics reflect actual state after compactions", () =>
     assert.equal(st.injectedCount, 0, "no injections yet");
     assert.equal(st.dedupHitRate, 0, "dedupHitRate is 0 with no injections");
     // Mark one injected and re-check
-    s.markInjected(SESS, "chkpt_001");
-    const st2 = s.stats(SESS);
+    vectorMarkInjected(s, SESS, "chkpt_001");
+    const st2 = vectorStats(s, SESS);
     assert.equal(st2.injectedCount, 1, "one injection tracked");
     assert.ok(Math.abs(st2.dedupHitRate - 1 / 3) < 1e-9, "dedupHitRate = injected/checkpoints");
 });
 test("9b. Stats on empty session returns zeros", () => {
     const s = store();
-    const st = s.stats("sess_nothing");
+    const st = vectorStats(s, "sess_nothing");
     assert.equal(st.checkpointCount, 0);
     assert.equal(st.totalTokenEstimate, 0);
     assert.equal(st.lastCheckpointId, undefined);
@@ -496,15 +496,15 @@ test("10. Concurrent sessions: no cross-contamination", () => {
     });
     // Verify: each session has exactly one checkpoint
     sessions.forEach((sess) => {
-        const cps = s.list(sess.id);
+        const cps = vectorList(s, sess.id);
         assert.equal(cps.length, 1, `${sess.id} should have 1 checkpoint`);
     });
     // Verify: search in one session doesn't return another session's checkpoints
-    const hitsA = s.search("sess_concurrent_a", "authentication JWT", 5);
+    const hitsA = vectorSearch(s, "sess_concurrent_a", "authentication JWT", 5);
     assert.ok(hitsA.every((h) => h.checkpoint.sessionId === "sess_concurrent_a"), "search in A returns only A's checkpoints");
-    const hitsB = s.search("sess_concurrent_b", "database queries indexes", 5);
+    const hitsB = vectorSearch(s, "sess_concurrent_b", "database queries indexes", 5);
     assert.ok(hitsB.every((h) => h.checkpoint.sessionId === "sess_concurrent_b"), "search in B returns only B's checkpoints");
-    const hitsC = s.search("sess_concurrent_c", "canvas rendering bug", 5);
+    const hitsC = vectorSearch(s, "sess_concurrent_c", "canvas rendering bug", 5);
     assert.ok(hitsC.every((h) => h.checkpoint.sessionId === "sess_concurrent_c"), "search in C returns only C's checkpoints");
 });
 // ---------------------------------------------------------------------------
@@ -516,7 +516,7 @@ test("11a. Empty session (no messages) — compactSession should skip", () => {
     assert.equal(r.skipped, true, "empty session should be skipped");
     assert.equal(r.summary, "");
     assert.equal(r.regionHash, "");
-    assert.equal(s.list("sess_empty_msgs").length, 0);
+    assert.equal(vectorList(s, "sess_empty_msgs").length, 0);
 });
 test("11b. Single message session — should skip or handle gracefully", () => {
     const s = store();
@@ -549,7 +549,7 @@ test("11c. Very large region text — should still compact and store", () => {
     assert.ok(r.checkpointId, "checkpoint created");
     assert.ok(r.summary.length > 0, "summary produced");
     // Verify it's searchable
-    const hits = s.search(SESS, "module feature fix review", 3);
+    const hits = vectorSearch(s, SESS, "module feature fix review", 3);
     assert.ok(hits.length > 0, "large checkpoint is searchable");
 });
 test("11d. Unicode and emoji content — should normalize and hash correctly", () => {
@@ -565,7 +565,7 @@ test("11d. Unicode and emoji content — should normalize and hash correctly", (
     assert.equal(r.skipped, false, "unicode conversation should compact");
     assert.ok(r.regionHash.length > 0, "regionHash computed for unicode content");
     // Verify the checkpoint exists and is searchable
-    const hits = s.search(SESS, "中文 translation 本地化", 3);
+    const hits = vectorSearch(s, SESS, "中文 translation 本地化", 3);
     assert.ok(hits.length > 0, "unicode checkpoint is searchable");
     // Verify regionHash is deterministic for the same unicode content
     const r2 = compactSession({ sessionId: SESS, messages, keepFrom: 4, timestamp: 2 }, s);
@@ -588,7 +588,7 @@ test("11e. All messages in preserve-recent window — nothing to compact", () =>
         timestamp: 1,
     }, s);
     assert.equal(r.skipped, true, "should skip when keepFrom=0 (nothing to compact)");
-    assert.equal(s.list("sess_all_preserved").length, 0, "no checkpoints stored");
+    assert.equal(vectorList(s, "sess_all_preserved").length, 0, "no checkpoints stored");
 });
 // ---------------------------------------------------------------------------
 // 12. Feature Flag Toggling
@@ -616,7 +616,7 @@ test("12a. L0_ENABLED=false — L0 does not collapse exact dups", () => {
     assert.equal(r1.deduped, false);
     // With L0 off (and L1/L2 off too), near-dup should NOT be collapsed
     assert.equal(r2.deduped, false, "L0 disabled → near-dup not collapsed");
-    assert.equal(s.list(SESS).length, 2, "both checkpoints stored when L0 is off");
+    assert.equal(vectorList(s, SESS).length, 2, "both checkpoints stored when L0 is off");
 });
 test("12b. MARK_ONLY_L1=true — L1 records but does not collapse", () => {
     // Disable L2 to isolate L1 behavior
@@ -637,9 +637,9 @@ test("12b. MARK_ONLY_L1=true — L1 records but does not collapse", () => {
     assert.equal(r1.deduped, false);
     // MARK_ONLY_L1 → L1 detects the near-dup but does NOT collapse
     assert.equal(r2.deduped, false, "MARK_ONLY_L1 → not collapsed");
-    assert.equal(s.list(SESS).length, 2, "both checkpoints stored (mark only)");
+    assert.equal(vectorList(s, SESS).length, 2, "both checkpoints stored (mark only)");
     // Both should be active (not removed)
-    const all = s.list(SESS);
+    const all = vectorList(s, SESS);
     assert.ok(all.every((c) => c.dedupStatus === "active"), "both rows active under MARK_ONLY");
 });
 test("12c. L2_ENABLED=false — L2 skipped but L0/L1 still work", () => {
@@ -688,7 +688,7 @@ test("12d. All tiers disabled — nothing deduped, everything stored", () => {
     });
     assert.equal(r1.deduped, false);
     assert.equal(r2.deduped, false, "all tiers off → nothing deduped");
-    assert.equal(s.list(SESS).length, 2, "both stored");
+    assert.equal(vectorList(s, SESS).length, 2, "both stored");
 });
 // ---------------------------------------------------------------------------
 // Cleanup

package/dist/src/engine.js

@@ -15,7 +15,7 @@ import { findSuperseded, supersede } from "./supersede.js";
 import { summarizeMessages, mergeCompactSummaries, formatCompactSummary } from "./compact.js";
 import { extractiveSummarize } from "./extractive.js";
 import { estimateSessionTokens, estimateBlockTokens } from "./tokens.js";
-import { computeRegionHash, VectorStore } from "./vectorStore.js";
+import { computeRegionHash, vectorWasInjected, vectorSearch, VectorStore } from "./vectorStore.js";
 /** Default store used by the convenience `compactSession`. */
 let defaultStore;
 export function getDefaultStore(stateDir) {
@@ -125,8 +125,8 @@ export function compactSession(input, store = getDefaultStore()) {
  * inject (Sprint 4 wires injection); this module only does the deduped search.
  */
 export function recall(input, store = getDefaultStore()) {
-    const hits = store.search(input.sessionId, input.query, input.limit ?? 3);
-    const newHits = input.skipInjected === false ? hits : hits.filter((h) => !store.wasInjected(input.sessionId, h.checkpoint.checkpointId));
+    const hits = vectorSearch(store, input.sessionId, input.query, input.limit ?? 3);
+    const newHits = input.skipInjected === false ? hits : hits.filter((h) => !vectorWasInjected(store, input.sessionId, h.checkpoint.checkpointId));
     return { hits, newHits };
 }
 /** Merge a freshly compacted summary into the prior persisted summary text. */

package/dist/src/engine.test.js

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { VectorStore } from "./vectorStore.js";
+import { VectorStore, vectorMarkInjected, vectorSearch } from "./vectorStore.js";
 import { compactSession, recall, mergeSummary, supersededCount } from "./engine.js";
 const baseTmp = mkdtempSync(join(tmpdir(), "mc-engine-"));
 let counter = 0;
@@ -35,7 +35,7 @@ test("compactSession supersedes then persists a checkpoint", () => {
     assert.equal(supersededCount(messages.slice(0, 4)), 1);
     assert.equal(r.compactedFrom, 4);
     // The persisted checkpoint is searchable.
-    assert.equal(s.search(SESS, "bug src/server.ts", 5).length, 1);
+    assert.equal(vectorSearch(s, SESS, "bug src/server.ts", 5).length, 1);
 });
 test("compactSession is idempotent on identical region (dedup sentinel)", () => {
     const s = store();
@@ -50,20 +50,20 @@ test("compactSession is idempotent on identical region (dedup sentinel)", () =>
     assert.equal(r1.deduped, false);
     assert.equal(r2.deduped, true);
     assert.equal(r1.checkpointId, r2.checkpointId);
-    assert.equal(s.search(SESS, "parser", 10).length, 1);
+    assert.equal(vectorSearch(s, SESS, "parser", 10).length, 1);
 });
 test("compactSession skipped when slice is empty", () => {
     const s = store();
     const r = compactSession({ sessionId: SESS, messages: [msg("user", "only tail")], keepFrom: 0 }, s);
     assert.equal(r.skipped, true);
-    assert.equal(s.search(SESS, "x", 5).length, 0);
+    assert.equal(vectorSearch(s, SESS, "x", 5).length, 0);
 });
 test("recall drops already-injected checkpoints", () => {
     const s = store();
     compactSession({ sessionId: SESS, messages: [msg("user", "investigated src/vectorStore.ts"), msg("assistant", "ok", "Edit")], keepFrom: 2, timestamp: 1 }, s);
     const first = recall({ sessionId: SESS, query: "vectorStore", limit: 5, skipInjected: true }, s);
     assert.equal(first.newHits.length, 1);
-    s.markInjected(SESS, first.hits[0].checkpoint.checkpointId);
+    vectorMarkInjected(s, SESS, first.hits[0].checkpoint.checkpointId);
     const second = recall({ sessionId: SESS, query: "vectorStore", limit: 5, skipInjected: true }, s);
     assert.equal(second.newHits.length, 0);
     // Without the skip flag, both hits still surface.
@@ -100,7 +100,7 @@ test("compactSession with useExtractive produces topicSummary on checkpoint", ()
     assert.equal(r.skipped, false);
     assert.ok(r.checkpointId, "checkpoint created");
     // The checkpoint should have topicSummary populated
-    const hits = s.search("sess_extr", "auth refactor", 5);
+    const hits = vectorSearch(s, "sess_extr", "auth refactor", 5);
     assert.ok(hits.length > 0);
     // topicSummary should be present on the stored checkpoint (via extractive path)
     assert.ok(hits[0].checkpoint.topicSummary, "topicSummary should be populated when useExtractive is true");

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);
+    });
+}