pi-mega-compact 0.11.5 → 0.11.7

package/dist/extensions/mega-events/separated-prompt.js

@@ -0,0 +1,248 @@
+/**
+ * extensions/mega-events/separated-prompt.ts — A1+A2 PLAN_V2 Phase 2+3
+ * Message Separation + Cache-Optimized Prompt Builder:
+ *   - buildSeparatedPrompt(): Basic 4-layer message separation (Phase 2).
+ *   - buildCacheOptimizedPrompt(): Insert Layer 2 (vector-optimized stable
+ *     context) between summary (Layer 1) and thread (Layer 3), ordered by
+ *     stripe stability DESC (Phase 3).
+ *   - detectTopicShift(): Cosine-similarity-based topic-shift detection.
+ *   - cosineSimilarity(): cosine similarity of two Float32Array embeddings.
+ *
+ * Layer order (Phase 3): 0 (system) -> 1 (summary) -> 2 (cache stripes) ->
+ * 3 (thread: user/assistant turns) -> 4 (tool results at tail).
+ *
+ * Feature-gated by MEGACOMPACT_CACHE_STRIPING (default OFF).
+ * MEGACOMPACT_MESSAGE_SEPARATION must also be ON for any layering to occur.
+ * Flag-OFF = byte-identical to pre-sprint — returns messages unchanged.
+ */
+import { openStore } from "../../src/store/sqlite/utils.js";
+import { getStateDir } from "../../src/store.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Default stripe limit: top 10 most stable chunks. */
+const DEFAULT_STRIPE_LIMIT = 10;
+/** Topic-shift threshold: similarity below this triggers a stripe refresh. */
+const TOPIC_SHIFT_THRESHOLD = 0.7;
+// ─── Build separated prompt (Phase 2) ────────────────────────────────────────
+/**
+ * Reorganize messages into stable layers for better prompt caching.
+ *
+ * Layer order: 0 (system) -> 1 (summary) -> 3 (thread: user/assistant turns) ->
+ * 4 (tool results at tail).
+ *
+ * Feature gate: MEGACOMPACT_MESSAGE_SEPARATION env var.  When OFF (default),
+ * returns `messages` unchanged (byte-identical to pre-sprint).
+ */
+export function buildSeparatedPrompt(messages, _opts) {
+    const flag = process.env.MEGACOMPACT_MESSAGE_SEPARATION;
+    if (flag === "0" || flag === "false" || flag === undefined || flag === "") {
+        return messages;
+    }
+    // pi's AgentMessage union has no "system" role — the system prompt lives in
+    // AgentState.systemPrompt, separate from this array. The cache-relevant,
+    // low-risk transformation is moving volatile tool results/executions to the
+    // tail so the stable prefix (user/assistant/summaries/custom) stays contiguous.
+    // Discriminate by role only — never reach into `.content`/`.tool_calls`,
+    // which are variant-specific and require narrowing.
+    const main = [];
+    const tail = [];
+    for (const m of messages) {
+        if (m.role === "toolResult" || m.role === "bashExecution") {
+            tail.push(m);
+        }
+        else {
+            main.push(m);
+        }
+    }
+    if (tail.length === 0)
+        return messages; // nothing to reorder — byte-identical
+    return [...main, ...tail];
+}
+// ─── Cosine similarity ───────────────────────────────────────────────────────
+/**
+ * Compute cosine similarity between two Float32Array embeddings.
+ * Returns a value in [0, 1] where 1 = identical direction.
+ * Returns 0 if either vector is zero or inputs are mismatched.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}
+// ─── Buffer ↔ Float32Array helpers ───────────────────────────────────────────
+/**
+ * Decode a Float32Array from a Buffer (little-endian float32 blob).
+ * Returns null on empty/undefined input.
+ */
+export function decodeEmbeddingBlob(buf) {
+    if (!buf || buf.length === 0)
+        return null;
+    return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
+/**
+ * Encode a Float32Array into a Buffer for DB storage.
+ */
+export function encodeEmbeddingBlob(vec) {
+    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+// ─── Topic-shift detection ───────────────────────────────────────────────────
+/**
+ * Detect whether the conversation topic has shifted between the current turn
+ * and the previous turn. Uses cosine similarity between topic embeddings.
+ *
+ * Returns `true` when similarity < TOPIC_SHIFT_THRESHOLD (0.7), meaning the
+ * stable cache prefix may need reordering.
+ *
+ * Returns `false` (no shift) when either embedding is missing.
+ */
+export function detectTopicShift(currentEmb, previousEmb) {
+    if (!currentEmb || !previousEmb)
+        return false;
+    return cosineSimilarity(currentEmb, previousEmb) < TOPIC_SHIFT_THRESHOLD;
+}
+// ─── Load embeddings from store ──────────────────────────────────────────────
+/**
+ * Load the topic embedding for a given turn from the embedding_cache table.
+ * Returns null if no embedding is stored for that turn.
+ */
+export function loadTopicEmbedding(stateDir, conversationId, turnIndex) {
+    const db = openStore(stateDir);
+    try {
+        const row = db.prepare(`SELECT embedding FROM embedding_cache WHERE content_hash = ?`).get(`topic:${conversationId}:${turnIndex}`);
+        if (!row)
+            return null;
+        return decodeEmbeddingBlob(row.embedding);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Store a topic embedding for a given turn in the embedding_cache table.
+ * Idempotent (INSERT OR REPLACE).
+ */
+export function storeTopicEmbedding(stateDir, conversationId, turnIndex, embedding) {
+    const db = openStore(stateDir);
+    try {
+        const contentHash = `topic:${conversationId}:${turnIndex}`;
+        const blob = encodeEmbeddingBlob(embedding);
+        db.prepare(`INSERT OR REPLACE INTO embedding_cache (content_hash, embedding, computed_at) VALUES (?, ?, ?)`).run(contentHash, blob, Date.now());
+    }
+    finally {
+        db.close();
+    }
+}
+// ─── Cache stripe management ─────────────────────────────────────────────────
+/**
+ * Refresh cache stripe assignments from the cache_stripes table for a given
+ * conversation/epoch. Returns rows ordered by stability DESC.
+ *
+ * This is called at the start of each turn (or on topic-shift) to ensure the
+ * stripe assignments reflect the latest stability scores.
+ */
+export function refreshStripeAssignments(stateDir, epochId, limit = DEFAULT_STRIPE_LIMIT) {
+    const db = openStore(stateDir);
+    try {
+        const rows = db.prepare(`SELECT chunk_id, stripe, stability, assigned_at, epoch_id
+       FROM cache_stripes
+       WHERE epoch_id = ?
+       ORDER BY stability DESC
+       LIMIT ?`).all(epochId, limit);
+        return rows;
+    }
+    finally {
+        db.close();
+    }
+}
+// ─── Build cache-optimized prompt (Phase 3) ──────────────────────────────────
+/**
+ * Build a cache-optimized prompt with 5 layers:
+ *   0 (system) -> 1 (summary) -> 2 (cache stripes) -> 3 (thread) -> 4 (tool)
+ *
+ * Feature gate: MEGACOMPACT_CACHE_STRIPING (default OFF). When OFF, delegates
+ * to buildSeparatedPrompt (byte-identical to Phase 2 behavior).
+ *
+ * When ON but MEGACOMPACT_MESSAGE_SEPARATION is OFF, also delegates to
+ * buildSeparatedPrompt (which returns messages unchanged).
+ */
+export function buildCacheOptimizedPrompt(messages, opts) {
+    const flag = process.env.MEGACOMPACT_CACHE_STRIPING;
+    if (flag === "0" || flag === "false" || flag === undefined || flag === "") {
+        // Flag OFF: delegate to buildSeparatedPrompt (byte-identical).
+        return buildSeparatedPrompt(messages, opts);
+    }
+    // Build the base 4-layer structure first.
+    const base = buildSeparatedPrompt(messages, opts);
+    // If base equals messages, separation is OFF — return unchanged.
+    if (base === messages)
+        return base;
+    const stateDir = opts?.stateDir ?? getStateDir();
+    // Layer 1 = leading branch/compaction summaries (the stable summary layer).
+    // There is no "system" role in pi's AgentMessage union, so Layer 0 is empty.
+    // Count leading summaries to find where to insert the cache-stripe layer.
+    let layer1End = 0;
+    for (let i = 0; i < base.length; i++) {
+        const r = base[i].role;
+        if (r === "branchSummary" || r === "compactionSummary") {
+            layer1End = i + 1;
+        }
+        else {
+            break;
+        }
+    }
+    // Lay out the result: Layer 1 (summaries) first.
+    const result = base.slice(0, layer1End);
+    // Insert Layer 2: cache stripes (stable context ordered by stability DESC).
+    // Try to find the most recent epoch.
+    const db = openStore(stateDir);
+    let epochId = null;
+    try {
+        const epoch = db.prepare(`SELECT epoch_id FROM checkpoint_epochs ORDER BY created_at DESC LIMIT 1`).get();
+        epochId = epoch?.epoch_id ?? null;
+    }
+    finally {
+        db.close();
+    }
+    if (epochId) {
+        const stripes = refreshStripeAssignments(stateDir, epochId);
+        if (stripes.length > 0) {
+            // Build a single user message with concatenated stripe content.
+            const stripeBlocks = [];
+            for (const s of stripes) {
+                // Load chunk content from context_chunks table.
+                const db2 = openStore(stateDir);
+                try {
+                    const chunk = db2.prepare(`SELECT normalized_text FROM context_chunks WHERE id = ?`).get(s.chunk_id);
+                    if (chunk?.normalized_text) {
+                        stripeBlocks.push(chunk.normalized_text);
+                    }
+                }
+                finally {
+                    db2.close();
+                }
+            }
+            if (stripeBlocks.length > 0) {
+                result.push({
+                    role: "user",
+                    content: stripeBlocks.join("\n\n---\n\n"),
+                    timestamp: Date.now(),
+                });
+            }
+        }
+    }
+    // Append remaining layers (3: thread, 4: tool results).
+    for (let i = layer1End; i < base.length; i++) {
+        result.push(base[i]);
+    }
+    return result;
+}

package/dist/extensions/mega-runtime/env-loader.js

@@ -0,0 +1,56 @@
+/**
+ * mega-runtime/env-loader.ts — load `.mega-compact.env` from the state dir.
+ *
+ * The /mega-setup wizard and the dashboard Setup tab write a `.mega-compact.env`
+ * file with the user's chosen embedder configuration. Without a loader, that
+ * file is write-only dead weight — config is read from process.env at startup
+ * (mega-config.ts:loadConfig), so the file was never applied.
+ *
+ * This loader runs BEFORE loadConfig in the extension entry. It parses the
+ * file (KEY=VALUE lines, # comments, quoted values) and applies each key to
+ * process.env ONLY if it is not already set — so shell profile / inline env
+ * vars always win over the file (the user can override without editing it).
+ *
+ * Non-fatal: a missing or malformed file never breaks the extension.
+ *
+ * PREVENT-PI-004: reads a local file only — no network.
+ * PREVENT-001: no JSON here; line parser is null/empty-safe.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Load `.mega-compact.env` from `stateDir` into `process.env`.
+ * Keys already set in the environment win (file does not override shell).
+ */
+export function loadMegaEnv(stateDir) {
+    const envPath = join(stateDir, ".mega-compact.env");
+    if (!existsSync(envPath))
+        return;
+    let content;
+    try {
+        content = readFileSync(envPath, "utf-8");
+    }
+    catch {
+        return; // unreadable — non-fatal
+    }
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        if (!key)
+            continue;
+        let val = trimmed.slice(eq + 1).trim();
+        if ((val.startsWith('"') && val.endsWith('"')) ||
+            (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+        }
+        // Shell / inline env vars win over the file.
+        if (process.env[key] === undefined) {
+            process.env[key] = val;
+        }
+    }
+}

package/dist/extensions/mega-runtime/reset-runtime.js

@@ -27,6 +27,7 @@ export function resetRuntimeImpl(self, sessionId) {
         lastRecallAt: null,
         lastInjectAt: null,
         _prevCacheHitPct: null,
+        _lastCacheHealthScore: undefined,
         lastNativeCompactAt: null,
         compactCount: 0,
         recallInjections: 0,

package/dist/extensions/mega-runtime/runtime-snapshot.js

@@ -176,6 +176,7 @@ export function snapshotImpl(self, ctx) {
             armed,
             modelSnap,
             providerCachePct,
+            perTurnCacheHitPct: self.rt._prevCacheHitPct ?? undefined,
         });
         self.widgetData = _snapResult.widgetData;
         // S33: consume the flare after copying it into widgetData so it fires

package/dist/extensions/mega-runtime/runtime.js

@@ -52,6 +52,7 @@ export class MegaRuntime {
         lastRecallAt: null,
         lastInjectAt: null,
         _prevCacheHitPct: null,
+        _lastCacheHealthScore: undefined,
         lastNativeCompactAt: null,
         compactCount: 0,
         recallInjections: 0,

package/dist/extensions/mega-runtime/snapshot.js

@@ -131,6 +131,7 @@ export function computeMegaSnapshot(p) {
         cachePct,
         megaCacheFlare: p.megaCacheFlare,
         megaCacheFlarePct: p.megaCacheFlarePct,
+        perTurnCacheHitPct: p.perTurnCacheHitPct ?? cachePct,
         levelUpFlare: p.levelUpFlare,
         achievementFlare: p.achievementFlare,
         achievementFlareTitles: p.achievementFlareTitles,

package/dist/extensions/mega-runtime/widget.js

@@ -87,6 +87,11 @@ export function buildWidgetLines(wd, width, activeAgents) {
         `${C.gray}mem${C.reset} ${wd.embedderName} · ${wd.chk} chunks · ${C.blue}comp ${wd.compStr}${C.reset}`,
         `${C.gray}drift${C.reset} ${wd.driftStatus === "ok" ? C.green : C.amber}${wd.driftStatus}${C.reset}`,
         `${C.gray}compact${C.reset} ${sinceCompactStr(wd.sinceCompact)}`,
+        ...(wd.perTurnCacheHitPct != null
+            ? [
+                `${C.gray}cache hit${C.reset} this turn ${C.green}${Math.round(wd.perTurnCacheHitPct)}%${C.reset}`,
+            ]
+            : []),
     ].join(sep);
     // Wrap to terminal width and pad each line
     const wrapped = wrapLine(content, width - 2, panelBg); // 2-char indent

package/dist/src/cache-stripe-impl.js

@@ -0,0 +1,288 @@
+/**
+ * cache-stripe-impl.ts — Vector-Aware Cache Striping implementation.
+ *
+ * Computes a stability score for each context chunk and assigns it to a
+ * cache stripe / prompt-cache layer. Stable chunks (high recency + frequency +
+ * semantic density) go to early layers (cached prefix); volatile chunks append
+ * at Layer 4 (tail). Runs entirely offline — no network, no LLM (PREVENT-PI-004).
+ *
+ * The stability score is a weighted composite:
+ *   stability = 0.5 * semanticSimilarity + 0.3 * recency + 0.2 * frequency
+ *
+ * - semanticSimilarity: cosine similarity of the chunk's embedding against the
+ *   running session embedding (from TrigramEmbedder). High similarity means the
+ *   chunk is topically relevant to current work.
+ * - recency: how recently the chunk appeared (normalized to 0.0-1.0 across all
+ *   chunks in the epoch). Recent chunks are more likely to benefit from caching.
+ * - frequency: how often the chunk's content has been referenced (0.0-1.0,
+ *   estimated from a simple access counter stored alongside).
+ *
+ * Reassignment happens at epoch boundaries via refreshStripeAssignments.
+ * All SQL is parameterized (PREVENT-002). No pi runtime types are imported,
+ * keeping this module pi-agnostic.
+ */
+import { randomBytes } from "node:crypto";
+import { openStore, withTx } from "./store/sqlite/utils.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Semantic similarity weight in the composite score. */
+const WEIGHT_SEMANTIC = 0.5;
+/** Recency weight in the composite score. */
+const WEIGHT_RECENCY = 0.3;
+/** Frequency weight in the composite score. */
+const WEIGHT_FREQUENCY = 0.2;
+/** Stripes a chunk lands in based on its stability score. Thresholds define
+ *  the boundary between adjacent layers. */
+const STRIPE_THRESHOLDS = [
+    { minStability: 0.90, stripe: 0 },
+    { minStability: 0.70, stripe: 1 },
+    { minStability: 0.50, stripe: 2 },
+    { minStability: 0.30, stripe: 3 },
+    { minStability: -Infinity, stripe: 4 },
+];
+// ─── Embedding helpers (no external dep) ─────────────────────────────────────
+/**
+ * FNV-1a 32-bit hash for the content-based embedding fallback. The production
+ * path uses TrigramEmbedder from embedder.ts but we keep a self-contained hash
+ * for the case where no embedder is passed in.
+ */
+function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0) / 0x100000000;
+}
+/**
+ * Produce a crude 128-dim pseudorandom embedding from text using hashed n-gram
+ * bins. Matches the approach in TrigramEmbedder._embedRaw conceptually. Used
+ * only as a fallback / test path; the caller should prefer TrigramEmbedder.
+ */
+function fallbackEmbed(text) {
+    const dim = 128;
+    const vec = new Array(dim).fill(0);
+    const norm = text.toLowerCase().replace(/\s+/g, " ");
+    if (norm.length === 0)
+        return vec;
+    vec[Math.floor(fnv1a(norm) * dim)] += 1;
+    for (const word of norm.split(" ")) {
+        if (word.length === 0)
+            continue;
+        vec[Math.floor(fnv1a(word) * dim)] += 0.5;
+        for (let i = 0; i < Math.max(1, word.length - 1); i++) {
+            const trigram = word.slice(i, i + 3);
+            if (trigram.length === 3) {
+                vec[Math.floor(fnv1a(trigram) * dim)] += 0.25;
+            }
+        }
+    }
+    return l2Normalize(vec);
+}
+function l2Normalize(v) {
+    let sumSq = 0;
+    for (let i = 0; i < v.length; i++)
+        sumSq += v[i] * v[i];
+    if (sumSq === 0)
+        return v;
+    const norm = Math.sqrt(sumSq);
+    for (let i = 0; i < v.length; i++)
+        v[i] /= norm;
+    return v;
+}
+/** Compute cosine similarity between two vectors of equal length. */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ─── Stability Scoring ───────────────────────────────────────────────────────
+/**
+ * Compute a composite stability score for a single chunk.
+ *
+ * @param chunk         The chunk metadata + content to score.
+ * @param allChunks     All chunks in this epoch (used to compute relative recency).
+ * @param embedder      Optional embedder instance. If omitted, uses the
+ *                      self-contained fallback (128-dim hashed n-gram).
+ * @param sessionEmbed  Pre-computed embedding for the current session (the
+ *                      "query" vector). If omitted, computed on the fly from
+ *                      the chunk content alone, which degrades semantic scoring
+ *                      to a self-similarity baseline.
+ * @returns             A number in [0.0, 1.0] where 1.0 = most stable.
+ */
+export function computeStabilityScore(chunk, allChunks, embedder, sessionEmbed) {
+    // ── Semantic similarity (0.5 weight) ────────────────────────────────────
+    const emb = embedder
+        ? embedder.embed(chunk.content)
+        : fallbackEmbed(chunk.content);
+    // If no session embedding is provided, use the chunk's own embedding as
+    // a self-similarity — this produces a baseline score based on content
+    // density (chunks with more meaningful content get higher internal
+    // similarity). Real deployments should pass the session embedding.
+    const sem = cosineSimilarity(emb, sessionEmbed ?? emb);
+    const semanticScore = isNaN(sem) ? 0 : sem;
+    // ── Recency (0.3 weight) ────────────────────────────────────────────────
+    // Relative recency: lastAccessedAt of this chunk vs. min/max across epoch.
+    // Falls back to 0.5 if there's only one chunk or no timestamp data.
+    let recencyScore = 0.5;
+    const accessed = allChunks
+        .map((c) => c.lastAccessedAt)
+        .filter((t) => t > 0);
+    if (accessed.length > 1) {
+        const minT = Math.min(...accessed);
+        const maxT = Math.max(...accessed);
+        const range = maxT - minT;
+        if (range > 0) {
+            recencyScore = (chunk.lastAccessedAt - minT) / range;
+        }
+        else {
+            recencyScore = 1.0;
+        }
+    }
+    // ── Frequency (0.2 weight) ──────────────────────────────────────────────
+    // Access count relative to the max across the epoch.
+    const counts = allChunks.map((c) => c.accessCount);
+    const maxCount = Math.max(...counts, 1);
+    const freqScore = maxCount > 0 ? chunk.accessCount / maxCount : 0;
+    // ── Composite ───────────────────────────────────────────────────────────
+    const stability = WEIGHT_SEMANTIC * semanticScore +
+        WEIGHT_RECENCY * recencyScore +
+        WEIGHT_FREQUENCY * freqScore;
+    // Clamp to [0.0, 1.0] as a safety net.
+    return Math.max(0, Math.min(1, stability));
+}
+/**
+ * Determine the cache stripe (layer) for a given stability score.
+ *
+ * @param stability  Composite stability score in [0.0, 1.0].
+ * @returns          Stripe number 0-4.
+ */
+export function stabilityToStripe(stability) {
+    for (const t of STRIPE_THRESHOLDS) {
+        if (stability >= t.minStability)
+            return t.stripe;
+    }
+    return 4;
+}
+// ─── Stripe Reassignment ─────────────────────────────────────────────────────
+/**
+ * Refresh stripe assignments for all chunks in the current epoch.
+ *
+ * Steps:
+ *  1. Read all context_chunks from the SQLite store that belong to the
+ *     current epoch (or all chunks if no epoch filter).
+ *  2. For each chunk, compute a stability score via computeStabilityScore.
+ *  3. Map stability -> stripe via stabilityToStripe.
+ *  4. UPSERT into cache_stripes.
+ *  5. (Stale entries for this epoch are implicitly overwritten by the UPSERT.)
+ *
+ * The optional embedder parameter allows injecting the production
+ * TrigramEmbedder. If omitted, the fallback hashed n-gram embedder is used
+ * (works offline in all scenarios).
+ *
+ * Non-fatal: failures are logged via a provided logger callback and never
+ * thrown. Returns the count of chunks reassigned.
+ *
+ * @param store      An open SQLite DatabaseSync handle (or a stateDir string
+ *                   to open lazily). Accepts either to match the caller's
+ *                   convenience. When a string is passed, opens the store for
+ *                   this call only (does not cache the connection).
+ * @param epochId    The epoch to reassign. If omitted, generates a new epoch
+ *                   ID (random hex). Pass '' to reassign all chunks without
+ *                   filtering by epoch.
+ * @param embedder   Optional TrigramEmbedder instance. When provided, uses it
+ *                   for semantic similarity; otherwise uses the fallback.
+ * @param logFn      Optional logging callback (defaults to no-op).
+ * @returns          The number of chunks that were reassigned.
+ */
+export function refreshStripeAssignments(store, epochId, embedder, logFn) {
+    const db = typeof store === "string" ? openStore(store) : store;
+    const log = logFn ?? (() => { });
+    const actualEpochId = epochId ?? nextEpochId();
+    const now = Math.floor(Date.now() / 1000);
+    try {
+        // 1. Read all relevant context_chunks, using the summary as text content.
+        //    The summary field holds the compressed checkpoint content; for fresh
+        //    chunks that have no summary yet, fall back to normalized_text or
+        //    concatenated key_decisions.
+        const rows = db
+            .prepare(`SELECT c.rowid AS chunk_id,
+                COALESCE(c.summary, c.normalized_text, c.key_decisions, '') AS content,
+                COALESCE(s.access_count, 0) AS access_count,
+                COALESCE(s.last_accessed_at, 0) AS last_accessed_at
+         FROM context_chunks c
+         LEFT JOIN cache_stripes s ON s.chunk_id = CAST(c.rowid AS TEXT)
+         WHERE (? = '' OR s.epoch_id = ? OR s.epoch_id IS NULL)`)
+            .all(actualEpochId, actualEpochId);
+        if (rows.length === 0) {
+            log("cache-stripe: no chunks to reassign");
+            return 0;
+        }
+        // Build the allChunks array for relative scoring.
+        const allChunks = rows.map((r) => ({
+            chunkId: String(r.chunk_id),
+            content: r.content,
+            accessCount: r.access_count,
+            lastAccessedAt: r.last_accessed_at,
+        }));
+        // Compute a session embedding (mean of all chunk embeddings) for semantic
+        // similarity comparison.
+        let sessionEmbed;
+        try {
+            const dim = embedder ? embedder.embed("").length : 128;
+            const sumEmb = new Array(dim).fill(0);
+            let count = 0;
+            for (const chunk of allChunks) {
+                const vec = embedder
+                    ? embedder.embed(chunk.content)
+                    : fallbackEmbed(chunk.content);
+                for (let i = 0; i < sumEmb.length; i++)
+                    sumEmb[i] += vec[i];
+                count++;
+            }
+            if (count > 0) {
+                for (let i = 0; i < sumEmb.length; i++)
+                    sumEmb[i] /= count;
+                sessionEmbed = l2Normalize(sumEmb);
+            }
+        }
+        catch {
+            log("cache-stripe: session embedding failed, skipping semantic weight");
+        }
+        // 2. Compute stability for each chunk.
+        const results = [];
+        for (const chunk of allChunks) {
+            const stability = computeStabilityScore(chunk, allChunks, embedder, sessionEmbed);
+            const stripe = stabilityToStripe(stability);
+            results.push({ chunkId: chunk.chunkId, stripe, stability });
+        }
+        // 3. UPSERT into cache_stripes using a savepoint for atomicity.
+        const upsert = db.prepare(`INSERT OR REPLACE INTO cache_stripes(chunk_id, stripe, stability, assigned_at, epoch_id)
+       VALUES (?, ?, ?, ?, ?)`);
+        withTx(db, () => {
+            for (const r of results) {
+                upsert.run(r.chunkId, r.stripe, r.stability, now, actualEpochId);
+            }
+        });
+        log(`cache-stripe: reassigned ${results.length} chunks to epoch ${actualEpochId}`);
+        return results.length;
+    }
+    catch (err) {
+        log(`cache-stripe: refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 0;
+    }
+}
+/**
+ * Generate a random epoch ID (16 hex chars) for tokenizing stripe cohorts.
+ */
+function nextEpochId() {
+    return randomBytes(8).toString("hex");
+}

package/dist/src/cache-stripe.js

@@ -0,0 +1,11 @@
+/**
+ * cache-stripe.ts — Vector-Aware Cache Striping shell (PLAN_V2 Phase 3).
+ *
+ * Shell: re-exports types and function signatures from the implementation.
+ * The heavy logic lives in cache-stripe-impl.ts. This keeps the public API
+ * surface clean and respects the src/ 300-line soft limit.
+ *
+ * Pi-agnostic: no pi runtime types, no network (PREVENT-PI-004).
+ * All SQL is parameterized (PREVENT-002).
+ */
+export { computeStabilityScore, stabilityToStripe, refreshStripeAssignments, } from "./cache-stripe-impl.js";

package/dist/src/config/stopwords.js

@@ -0,0 +1,24 @@
+/**
+ * config/stopwords.ts — shared stopword set for query expansion, coverage
+ * metrics, and term tokenization (S45, PREREQUISITE P2).
+ *
+ * Single source of truth: both `src/queryExpansion.ts` and `src/recallMetrics.ts`
+ * import from here instead of duplicating inline sets.
+ *
+ * Pi-agnostic, zero deps, tree-shake safe.
+ */
+/** Default English stopwords. */
+export const STOP_WORDS = new Set([
+    "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+    "of", "with", "by", "from", "as", "is", "was", "are", "were", "be",
+    "been", "has", "have", "had", "do", "does", "did", "will", "would",
+    "could", "should", "may", "might", "shall", "can", "not", "no", "nor",
+    "so", "if", "then", "than", "that", "this", "these", "those", "it",
+    "its", "i", "me", "my", "we", "our", "you", "your", "he", "she",
+    "they", "them", "their", "what", "which", "who", "whom", "when",
+    "where", "why", "how", "all", "each", "every", "both", "few", "more",
+    "most", "other", "some", "such", "only", "own", "same", "so", "than",
+    "too", "very", "just", "about", "above", "after", "again", "against",
+    "because", "before", "between", "down", "during", "out", "over",
+    "through", "under", "up", "also", "into", "off", "onto", "upon",
+]);