pi-mega-compact 0.4.5 → 0.4.7

package/dist/src/dedup/raptor/index.js

@@ -0,0 +1,94 @@
+/**
+ * index.ts — RAPTOR orchestrator (Sprint 13, Phase 6).
+ *
+ * Entry point that turns a session's leaves into a hierarchical summary tree.
+ * Shadow mode (RAPTOR_SHADOW_MODE default true): the tree is BUILT and PERSISTED
+ * to raptor_nodes + logged, but is NOT used to serve retrieval. The live
+ * vectorStore.search path is untouched until Sprint 14 promotes RAPTOR.
+ *
+ * PREVENT-PI-004: no network here. Any Ollama call lives in summarizer.ts
+ * (localhost-only, annotated). This module is pure orchestration.
+ */
+import { defaultEmbedder } from "../../embedder.js";
+import { buildRaptorTree } from "./tree.js";
+import { stagedExpansion } from "./retrieval.js";
+import { saveRaptorTree, listRaptorNodes } from "../../store/sqlite.js";
+/** Shadow mode is on by default; set RAPTOR_SHADOW_MODE=false to serve live. */
+export function isShadowMode() {
+    return process.env.RAPTOR_SHADOW_MODE !== "false";
+}
+/**
+ * Build the RAPTOR tree for a session's leaves. Per shadow-mode rules, the tree
+ * is persisted + logged regardless; whether it is served is the caller's choice
+ * (Sprint 13: it is built but NOT injected into recallAndInline).
+ *
+ * Returns the built tree (in-memory) for eval/tests, and persists it to the
+ * store. Never throws — on any build error it logs and returns null.
+ */
+export function runRaptor(leaves, opts) {
+    const embedder = opts.embedder ?? defaultEmbedder();
+    const logger = opts.logger;
+    try {
+        const tree = buildRaptorTree(leaves, {
+            embedder,
+            budgetMs: opts.budgetMs,
+            clustersPerLevel: opts.clustersPerLevel,
+            consistencyThreshold: opts.consistencyThreshold,
+        });
+        saveRaptorTree(opts.sessionId, tree, opts.stateDir);
+        logger?.info("raptor_build", {
+            sessionId: opts.sessionId,
+            nodes: tree.nodes.size,
+            levels: tree.levels,
+            rootId: tree.rootId,
+            timedOut: tree.timedOut,
+            shadow: isShadowMode(),
+        });
+        if (isShadowMode()) {
+            // Build + log only. Do NOT replace retrieval.
+            logger?.info("raptor_shadow", { sessionId: opts.sessionId, served: false });
+        }
+        return tree;
+    }
+    catch (e) {
+        logger?.error("raptor_build_failed", {
+            sessionId: opts.sessionId,
+            error: String(e instanceof Error ? e.message : e),
+        });
+        return null;
+    }
+}
+/**
+ * Staged retrieval over a persisted/session tree. Only meaningful when RAPTOR
+ * is promoted (Sprint 14); provided here so eval can measure it in shadow.
+ *
+ * Returns the leaf ids the staged expansion would serve for `query`.
+ */
+export function recallRaptor(query, sessionId, opts) {
+    const embedder = opts.embedder ?? defaultEmbedder();
+    const nodes = listRaptorNodes(sessionId, opts.stateDir);
+    if (nodes.length === 0)
+        return [];
+    // Rehydrate a minimal in-memory tree (parent links reconstructed from children).
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const tree = {
+        nodes: new Map(nodes.map((n) => [
+            n.id,
+            {
+                id: n.id,
+                level: n.level,
+                parentId: n.parentId,
+                children: n.children,
+                summary: n.summary,
+                embedding: n.embedding,
+                qualityMarker: n.qualityMarker,
+                tokenEstimate: n.tokenEstimate,
+            },
+        ])),
+        rootId: nodes.reduce((best, n) => (!best || n.level > (best?.level ?? -1) ? n : best), null)?.id ?? null,
+        levels: Math.max(1, ...nodes.map((n) => n.level + 1)),
+        timedOut: false,
+    };
+    void byId;
+    return stagedExpansion(query, tree, { embedder, k: opts.k, topM: opts.topM });
+}

package/dist/src/dedup/raptor/kmeans.js

@@ -0,0 +1,152 @@
+/**
+ * kmeans.ts — k-means++ clustering over embeddings (Sprint 13, RAPTOR Phase 6).
+ *
+ * Pure TS, zero deps, deterministic (seeded). Used to group leaf chunks into
+ * nodes for the RAPTOR summary tree. QA #11: GMM is the spec's long-term target
+ * for cosine space; k-means++ is the shippable local default, with a
+ * near-zero-variance merge guard so degenerate inputs can't spin forever.
+ *
+ * PREVENT-PI-004: math only, no network, no model.
+ */
+import { cosineSimilarity } from "../../embedder.js";
+/** Seeded PRNG (mulberry32) so clustering is deterministic across runs. */
+function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** L2 distance squared between two equal-length vectors. */
+function dist2(a, b) {
+    let s = 0;
+    for (let i = 0; i < a.length; i++) {
+        const d = a[i] - b[i];
+        s += d * d;
+    }
+    return s;
+}
+/**
+ * k-means++ clustering. Deterministic given `seed`.
+ *
+ * Near-zero-variance guard (QA #11): if the max pairwise distance among input
+ * points is below `varianceFloor`, all points are effectively identical — return
+ * a single cluster (the mean) instead of iterating. Prevents the centroid-init
+ * from dividing by ~0 and keeps degenerate sessions from spinning.
+ */
+export function kmeanspp(points, k, opts = {}) {
+    const n = points.length;
+    const seed = opts.seed ?? 0x9e3779b9;
+    const maxIter = opts.maxIter ?? 25;
+    const varianceFloor = opts.varianceFloor ?? 1e-12;
+    if (n === 0)
+        return { assignments: [], centroids: [], k: 0 };
+    if (n === 1)
+        return { assignments: [0], centroids: [points[0].slice()], k: 1 };
+    // Near-zero-variance merge guard.
+    let maxPair = 0;
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            const d = dist2(points[i], points[j]);
+            if (d > maxPair)
+                maxPair = d;
+        }
+    }
+    if (maxPair < varianceFloor) {
+        const mean = new Array(points[0].length).fill(0);
+        for (const p of points)
+            for (let i = 0; i < mean.length; i++)
+                mean[i] += p[i] / n;
+        return { assignments: new Array(n).fill(0), centroids: [mean], k: 1 };
+    }
+    const kk = Math.min(k, n);
+    const rand = rng(seed);
+    // k-means++ seeding: first centroid random, rest weighted by squared distance.
+    const centroids = [points[Math.floor(rand() * n)].slice()];
+    const d2 = new Array(n).fill(Infinity);
+    while (centroids.length < kk) {
+        let sum = 0;
+        for (let i = 0; i < n; i++) {
+            const d = dist2(points[i], centroids[centroids.length - 1]);
+            if (d < d2[i])
+                d2[i] = d;
+            sum += d2[i];
+        }
+        if (sum === 0) {
+            // All remaining points coincide with an existing centroid.
+            for (const p of points)
+                if (!centroids.some((c) => dist2(c, p) < 1e-12))
+                    centroids.push(p.slice());
+            break;
+        }
+        let target = rand() * sum;
+        let chosen = 0;
+        for (let i = 0; i < n; i++) {
+            target -= d2[i];
+            if (target <= 0) {
+                chosen = i;
+                break;
+            }
+        }
+        centroids.push(points[chosen].slice());
+    }
+    const assignments = new Array(n).fill(0);
+    for (let iter = 0; iter < maxIter; iter++) {
+        let changed = false;
+        // Assign each point to its nearest centroid.
+        for (let i = 0; i < n; i++) {
+            let best = 0;
+            let bestD = Infinity;
+            for (let c = 0; c < centroids.length; c++) {
+                const d = dist2(points[i], centroids[c]);
+                if (d < bestD) {
+                    bestD = d;
+                    best = c;
+                }
+            }
+            if (assignments[i] !== best) {
+                assignments[i] = best;
+                changed = true;
+            }
+        }
+        // Recompute centroids as the mean of assigned points.
+        const sums = centroids.map(() => new Array(points[0].length).fill(0));
+        const counts = new Array(centroids.length).fill(0);
+        for (let i = 0; i < n; i++) {
+            const c = assignments[i];
+            counts[c]++;
+            for (let d = 0; d < points[i].length; d++)
+                sums[c][d] += points[i][d];
+        }
+        for (let c = 0; c < centroids.length; c++) {
+            if (counts[c] === 0)
+                continue; // keep prior centroid if a cluster emptied
+            centroids[c] = sums[c].map((s) => s / counts[c]);
+        }
+        if (!changed && iter > 0)
+            break;
+    }
+    return { assignments, centroids, k: centroids.length };
+}
+/** Mean embedding of a set of vectors (used to reduce a cluster to its centroid). */
+export function meanVector(vectors) {
+    if (vectors.length === 0)
+        return [];
+    const dim = vectors[0].length;
+    const sum = new Array(dim).fill(0);
+    for (const v of vectors)
+        for (let i = 0; i < dim; i++)
+            sum[i] += v[i];
+    return sum.map((s) => s / vectors.length);
+}
+/** Centroid of the union of two clusters (cosine-space "midpoint" via mean). */
+export function mergeCentroids(a, b) {
+    return meanVector([a, b]);
+}
+/** Cosine distance (1 - cosine) — used by tree.ts for budget/quality checks. */
+export function cosineDistance(a, b) {
+    return 1 - cosineSimilarity(a, b);
+}

package/dist/src/dedup/raptor/raptor.test.js

@@ -0,0 +1,205 @@
+/**
+ * raptor.test.ts — hermetic unit tests for the Sprint 13 RAPTOR module.
+ *
+ * No network: the default summarizer is deterministic extractive, and Ollama is
+ * only reached when MEGACOMPACT_RAPTOR_MODEL is set (never here). Retrieval from
+ * the live store is never touched (shadow mode), so recallAndInline output is
+ * unchanged by construction.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { TrigramEmbedder } from "../../embedder.js";
+import { kmeanspp } from "./kmeans.js";
+import { applyHallucinationGuardrails, sourceTokenSet, extractEntities, makeUngroundedSummary, } from "./guardrails.js";
+import { buildRaptorTree } from "./tree.js";
+import { stagedExpansion } from "./retrieval.js";
+import { runRaptor } from "./index.js";
+import { Logger } from "../../log.js";
+import { listRaptorNodes, clearRaptorNodes, closeStore, } from "../../store/sqlite.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-raptor-"));
+function msg(text) {
+    return { role: "user", text };
+}
+/** Build N distinct leaves with deterministic content. */
+function makeLeaves(n, embedder = new TrigramEmbedder()) {
+    const leaves = [];
+    for (let i = 0; i < n; i++) {
+        const text = `topic ${i % 7}: the module ${i} validated the session token and refreshed the cache for region ${i}`;
+        leaves.push({
+            id: `leaf_${i}`,
+            messages: [msg(text)],
+            sourceText: text,
+            embedding: embedder.embed(text),
+        });
+    }
+    return leaves;
+}
+// --- kmeans: near-zero-variance merge guard ---------------------------------
+test("kmeanspp merges identical points into a single cluster (QA #11)", () => {
+    const p = [1, 0, 0];
+    const points = [p, p, p, p, p];
+    const r = kmeanspp(points, 3, { seed: 1 });
+    assert.equal(r.k, 1);
+    assert.deepEqual(r.assignments, [0, 0, 0, 0, 0]);
+});
+test("kmeanspp separates two well-separated clusters", () => {
+    const a = [1, 0, 0];
+    const b = [0, 1, 0];
+    const points = [a, a, a, b, b, b];
+    const r = kmeanspp(points, 2, { seed: 7 });
+    assert.equal(r.k, 2);
+    // All the a's share one assignment, all the b's another.
+    const firstGroup = r.assignments[0];
+    const secondGroup = r.assignments[3];
+    assert.notEqual(firstGroup, secondGroup);
+    for (let i = 0; i < 3; i++)
+        assert.equal(r.assignments[i], firstGroup);
+    for (let i = 3; i < 6; i++)
+        assert.equal(r.assignments[i], secondGroup);
+});
+// --- guardrails: catch hallucination (QA #16) ------------------------------
+test("guardrails flag an un-grounded entity as extractive_fallback", () => {
+    const embedder = new TrigramEmbedder();
+    const realSource = "the auth module validates the session token";
+    const summary = makeUngroundedSummary(realSource, "ZkPhant0mCorp");
+    const sources = [realSource];
+    const r = applyHallucinationGuardrails({
+        summary,
+        sources,
+        centroid: embedder.embed(realSource),
+        embedder,
+        sourceTokens: sourceTokenSet(sources),
+    });
+    assert.equal(r.marker, "extractive_fallback");
+    assert.equal(r.grounded, false);
+});
+test("guardrails pass a faithful, grounded summary", () => {
+    const embedder = new TrigramEmbedder();
+    const src = "the auth module validates the session token and refreshes the cache";
+    const summary = "the auth module validates the session token";
+    const sources = [src];
+    const r = applyHallucinationGuardrails({
+        summary,
+        sources,
+        centroid: embedder.embed(src),
+        embedder,
+        sourceTokens: sourceTokenSet(sources),
+    });
+    assert.equal(r.grounded, true);
+    assert.ok(r.marker === "high" || r.marker === "low");
+    assert.notEqual(r.marker, "extractive_fallback");
+});
+test("extractEntities lowercases candidate tokens", () => {
+    const e = extractEntities("The AuthModule validates the token_abc 42 times");
+    assert.ok(e.includes("authmodule"));
+    assert.ok(e.includes("token_abc"));
+});
+// --- tree: <10 leaves → single node -----------------------------------------
+test("tree with <10 leaves yields a single root node", () => {
+    const leaves = makeLeaves(5);
+    const tree = buildRaptorTree(leaves, { embedder: new TrigramEmbedder() });
+    assert.equal(tree.nodes.size, 1);
+    assert.equal(tree.rootId, "r0_0");
+    assert.equal(tree.levels, 1);
+    assert.equal(tree.timedOut, false);
+});
+// --- tree: 1K fixture builds within budget ----------------------------------
+test("tree builds within 5s on a 1000-leaf fixture", () => {
+    const leaves = makeLeaves(1000);
+    const t0 = Date.now();
+    const tree = buildRaptorTree(leaves, {
+        embedder: new TrigramEmbedder(),
+        budgetMs: 5000,
+        clustersPerLevel: 8,
+    });
+    const elapsed = Date.now() - t0;
+    assert.ok(elapsed < 5000, `build took ${elapsed}ms (over 5s budget)`);
+    assert.ok(tree.nodes.size > 1, "expected a multi-level tree");
+    assert.ok(tree.rootId !== null);
+});
+// --- tree: budget timeout → extractive fallback root ------------------------
+test("tree respects the budget: a tiny budget forces an extractive fallback root", () => {
+    const leaves = makeLeaves(200);
+    const tree = buildRaptorTree(leaves, {
+        embedder: new TrigramEmbedder(),
+        budgetMs: 0, // forces immediate timeout on the first level
+        clustersPerLevel: 4,
+    });
+    assert.equal(tree.timedOut, true);
+    assert.equal(tree.rootId, "r99_0");
+    assert.ok(tree.nodes.has("r99_0"));
+});
+// --- retrieval: staged expansion returns leaf ids ---------------------------
+test("stagedExpansion returns diversified leaf ids for a query", () => {
+    const leaves = makeLeaves(20);
+    const tree = buildRaptorTree(leaves, { embedder: new TrigramEmbedder(), clustersPerLevel: 4 });
+    const hits = stagedExpansion("the auth module validates the session token", tree, {
+        embedder: new TrigramEmbedder(),
+        k: 3,
+        topM: 3,
+    });
+    assert.ok(hits.length > 0);
+    assert.ok(hits.length <= 3);
+    // All returned ids are raw leaf ids (not internal node ids).
+    for (const id of hits)
+        assert.ok(id.startsWith("leaf_"));
+});
+// --- shadow mode: builds + persists, never alters retrieval -----------------
+test("runRaptor builds + persists a shadow tree without throwing", () => {
+    const dir = join(baseTmp, `shadow-${Math.floor(performance.now())}`);
+    const leaves = makeLeaves(40);
+    const logger = new Logger({
+        enabled: true,
+        now: () => 0,
+        path: join(dir, "events.log"),
+    });
+    const tree = runRaptor(leaves, {
+        stateDir: dir,
+        sessionId: "sess_raptor",
+        embedder: new TrigramEmbedder(),
+        logger,
+    });
+    assert.ok(tree !== null);
+    // Tree was persisted to raptor_nodes.
+    const stored = listRaptorNodes("sess_raptor", dir);
+    assert.ok(stored.length > 0, "shadow tree should be persisted");
+    // Quality markers are valid values.
+    for (const n of stored) {
+        assert.ok(["high", "low", "extractive_fallback"].includes(n.qualityMarker) || n.qualityMarker === "low");
+    }
+    clearRaptorNodes("sess_raptor", dir);
+    closeStore(dir);
+});
+test("shadow mode does NOT change recallAndInline output (separation)", () => {
+    // The orchestrator persists to raptor_nodes only. The live store's
+    // recallAndInline path (vectorStore.search) reads context_chunks, never
+    // raptor_nodes, so building a RAPTOR tree is observably independent.
+    const dir = join(baseTmp, `sep-${Math.floor(performance.now())}`);
+    const leaves = makeLeaves(15);
+    const before = listRaptorNodes("sess_sep", dir);
+    runRaptor(leaves, {
+        stateDir: dir,
+        sessionId: "sess_sep",
+        embedder: new TrigramEmbedder(),
+    });
+    const after = listRaptorNodes("sess_sep", dir);
+    // Building RAPTOR only ever writes raptor_nodes; context_chunks is untouched.
+    assert.deepEqual(before, []);
+    assert.ok(after.length > 0);
+    clearRaptorNodes("sess_sep", dir);
+    closeStore(dir);
+});
+// --- eval: redundancy reduction ≥ 15% (nodes << leaves) ---------------------
+test("eval: RAPTOR reduces node count substantially vs flat (≥15%)", () => {
+    const leaves = makeLeaves(100);
+    const tree = buildRaptorTree(leaves, { embedder: new TrigramEmbedder(), clustersPerLevel: 8 });
+    const reduction = 1 - tree.nodes.size / leaves.length;
+    assert.ok(reduction >= 0.15, `redundancy reduction ${reduction.toFixed(2)} < 0.15`);
+});
+// --- cleanup ----------------------------------------------------------------
+test("RAPTOR cleanup", () => {
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/src/dedup/raptor/retrieval.js

@@ -0,0 +1,81 @@
+/**
+ * retrieval.ts — staged RAPTOR retrieval (Sprint 13, Phase 6).
+ *
+ * Given a built tree (shadow or live), answer a query by:
+ *   1. ANN: score the top-level nodes at every level by cosine to the query.
+ *   2. expand: take the top-M nodes (across levels) and descend.
+ *   3. BFS: from those anchors, walk down to leaf nodes.
+ *   4. MMR: diversify the resulting leaf set before returning.
+ *
+ * This module is pure query logic over an in-memory RaptorTree. In Sprint 13 it
+ * is exercised only in shadow/eval; the live store (vectorStore.search) is NOT
+ * replaced until Sprint 14 promotes RAPTOR.
+ */
+import { cosineSimilarity } from "../../embedder.js";
+import { mmrRerank } from "../mmr.js";
+/** Any child id not present in the node map is a raw leaf id. */
+function isLeafId(id, tree) {
+    return !tree.nodes.has(id);
+}
+/** All leaf (raw) ids reachable beneath a node via BFS. */
+function leafDescendants(node, tree) {
+    const out = [];
+    const queue = [node];
+    while (queue.length) {
+        const cur = queue.shift();
+        for (const childId of cur.children) {
+            if (isLeafId(childId, tree))
+                out.push(childId);
+            else {
+                const child = tree.nodes.get(childId);
+                if (child)
+                    queue.push(child);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Staged expansion retrieval over a RAPTOR tree.
+ *
+ * Returns up to `k` leaf ids, diversified by MMR. Deterministic given the
+ * tree + query. Throws nothing — returns [] on empty tree.
+ */
+export function stagedExpansion(query, tree, opts) {
+    if (!tree.rootId)
+        return [];
+    const embedder = opts.embedder;
+    const topM = opts.topM ?? 3;
+    const k = opts.k ?? 5;
+    const lambda = opts.mmrLambda ?? 0.5;
+    const qv = embedder.embed(query);
+    // 1. ANN: score every node at every level by cosine to the query.
+    const scored = [...tree.nodes.values()].map((n) => ({
+        node: n,
+        score: cosineSimilarity(qv, n.embedding),
+    }));
+    // 2. expand: top-M nodes overall (BFS anchors).
+    const anchors = scored
+        .slice()
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topM)
+        .map((s) => s.node);
+    // 3. BFS to leaves from those anchors.
+    const leaves = new Map();
+    for (const a of anchors) {
+        for (const lid of leafDescendants(a, tree)) {
+            // Represent each leaf by its nearest internal parent so we can score it.
+            // (The leaf's own centroid is stored on the level-0 node that wraps it.)
+            const parent = [...tree.nodes.values()].find((n) => n.children.includes(lid));
+            if (parent)
+                leaves.set(lid, parent);
+        }
+    }
+    // 4. MMR diversify the expanded leaf set by their (parent) embeddings.
+    const items = [...leaves.entries()].map(([lid, n]) => ({
+        item: lid,
+        vector: n.embedding,
+        relevance: cosineSimilarity(qv, n.embedding),
+    }));
+    return mmrRerank(items, k, lambda);
+}

package/dist/src/dedup/raptor/summarizer.js

@@ -0,0 +1,85 @@
+/**
+ * summarizer.ts — per-cluster summary for the RAPTOR tree (Sprint 13, Phase 6).
+ *
+ * Default: pure extractive (deterministic, zero network, zero model) reusing
+ * extractive.ts. Optional: a LOCAL Ollama model (llama3.2:3b by default) when
+ * MEGACOMPACT_RAPTOR_MODEL is set — localhost only, same PREVENT-PI-004
+ * exception class as HttpEmbedder/the dashboard. No remote API is ever called.
+ *
+ * The summarizer returns structured text + a token estimate. Faithfulness is
+ * enforced downstream by guardrails.ts — this module only produces candidates.
+ */
+import { extractiveSummarize } from "../../extractive.js";
+import { estimateBlockTokens } from "../../tokens.js";
+import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: localhost-only user-spawned Ollama server (BYO local model, never remote)
+/** The local Ollama endpoint (loopback). Read lazily so tests can avoid it. */
+function ollamaEndpoint() {
+    const model = process.env.MEGACOMPACT_RAPTOR_MODEL;
+    if (!model)
+        return null;
+    const base = process.env.MEGACOMPACT_RAPTOR_URL ?? "http://127.0.0.1:11434";
+    // Guard: only loopback is permitted (remote Ollama would violate PREVENT-PI-004).
+    if (!/^https?:\/\/(localhost|127\.0\.0\.1)([:/]|$)/.test(base)) {
+        throw new Error(`MEGACOMPACT_RAPTOR_URL must be localhost/127.0.0.1 (got ${base}). ` +
+            `Remote Ollama is not allowed (PREVENT-PI-004).`);
+    }
+    return { url: `${base}/api/generate`, model };
+}
+/**
+ * Extractive summarization of a cluster's source messages. Deterministic and
+ * fully local — the on-by-default path.
+ */
+export function extractiveClusterSummary(messages) {
+    const s = extractiveSummarize(messages);
+    return { summary: s.topicSummary, tokenEstimate: s.tokenEstimate };
+}
+/**
+ * Build a summary for one cluster of source messages.
+ *
+ * Uses local Ollama when MEGACOMPACT_RAPTOR_MODEL is set (localhost-only);
+ * otherwise falls back to deterministic extractive. The `fetch` is a localhost
+ * call inside the PREVENT-PI-004 exception — annotated accordingly.
+ */
+export function summarizeCluster(messages) {
+    const ollama = ollamaEndpoint();
+    if (!ollama)
+        return extractiveClusterSummary(messages);
+    return ollamaSummarize(messages, ollama);
+}
+function ollamaSummarize(messages, ollama) {
+    // The fetch below is localhost-only (loopback Ollama) — the PREVENT-PI-004
+    // sanctioned local-model exceptions (same class as /dashboard, HttpEmbedder).
+    const prompt = messages.map((m) => `${m.role}: ${m.text}`).join("\n");
+    // Synchronous bridge: spawnSync an inline worker so the call blocks without
+    // deadlocking fetch (mirrors HttpEmbedder — Atomics.wait on main thread would
+    // hang). A blocked main thread cannot pump the socket.
+    const WORKER = String.raw `
+    const url = process.env.R_URL, model = process.env.R_MODEL, prompt = process.env.R_PROMPT;
+    try {
+      const r = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ model, prompt, stream: false }) }); // guardrails-allow PREVENT-PI-004: localhost-only user-spawned Ollama server (BYO local model, never remote)
+      const j = await r.json();
+      process.stdout.write(JSON.stringify({ ok: r.ok, text: j.response || "" }));
+    } catch (e) {
+      process.stdout.write(JSON.stringify({ ok: false, error: String(e && e.message ? e.message : e) }));
+    }
+  `;
+    const res = spawnSync(process.execPath, ["-e", WORKER], {
+        encoding: "utf8",
+        env: { ...process.env, R_URL: ollama.url, R_MODEL: ollama.model, R_PROMPT: prompt },
+    });
+    let parsed = { ok: false, error: "no response" };
+    if (typeof res.stdout === "string" && res.stdout.length > 0) {
+        try {
+            parsed = JSON.parse(res.stdout);
+        }
+        catch {
+            parsed = { ok: false, error: "bad json" };
+        }
+    }
+    if (!parsed.ok || !parsed.text) {
+        // Ollama unavailable → deterministic extractive fallback (never fail the build).
+        return extractiveClusterSummary(messages);
+    }
+    const summary = parsed.text.trim();
+    return { summary, tokenEstimate: estimateBlockTokens(summary) };
+}